react-native-chess-kit 0.1.0 → 0.2.1

package/src/use-board-gesture.ts

@@ -5,15 +5,47 @@ import {
   runOnJS,
 } from 'react-native-reanimated';
 
-import type { ChessColor, MoveMethod, BoardPiece, LegalMoveTarget, GestureState } from './types';
+import type {
+  ChessColor,
+  MoveMethod,
+  BoardPiece,
+  LegalMoveTarget,
+  GestureState,
+  PieceCode,
+  HapticType,
+  PremoveData,
+} from './types';
 import { xyToSquare } from './use-board-pieces';
 
+// ---------------------------------------------------------------------------
+// Callback types
+// ---------------------------------------------------------------------------
+
 type GestureCallbacks = {
   onPieceSelected: (square: string) => void;
   onPieceMoved: (from: string, to: string) => void;
   onSelectionCleared: () => void;
 };
 
+/** Rich callbacks exposed to consumers (all optional) */
+type RichCallbacks = {
+  onPieceClick?: (square: string, piece: PieceCode) => void;
+  onSquareClick?: (square: string) => void;
+  onPieceDragBegin?: (square: string, piece: PieceCode) => void;
+  onPieceDragEnd?: (square: string, piece: PieceCode) => void;
+  onSquareLongPress?: (square: string) => void;
+  onHaptic?: (type: HapticType) => void;
+};
+
+/** Premove-related callbacks from board.tsx */
+type PremoveCallbacks = {
+  onPremoveSet?: (premove: PremoveData) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Params
+// ---------------------------------------------------------------------------
+
 type UseBoardGestureParams = {
   squareSize: number;
   orientation: ChessColor;
@@ -22,10 +54,16 @@ type UseBoardGestureParams = {
   moveMethod: MoveMethod;
   pieces: BoardPiece[];
   callbacks: GestureCallbacks;
+  richCallbacks?: RichCallbacks;
+  premoveCallbacks?: PremoveCallbacks;
+  /** Whether premoves are enabled */
+  premovesEnabled?: boolean;
   /** Currently selected square (for tap-to-move second tap) */
   selectedSquare: string | null;
   /** Legal move targets from the currently selected piece */
   legalMoves: LegalMoveTarget[];
+  /** Whose turn it is ('w' or 'b') — used for premove detection */
+  currentTurn?: 'w' | 'b';
 };
 
 type UseBoardGestureReturn = {
@@ -33,6 +71,24 @@ type UseBoardGestureReturn = {
   gestureState: GestureState;
 };
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a piece color matches the current player turn */
+function isPieceTurn(pieceColor: 'w' | 'b', currentTurn: 'w' | 'b'): boolean {
+  return pieceColor === currentTurn;
+}
+
+/** Map piece color char to player ChessColor */
+function pieceColorToPlayer(color: 'w' | 'b'): ChessColor {
+  return color === 'w' ? 'white' : 'black';
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
 /**
  * Single centralized gesture handler for the entire board.
  *
@@ -51,6 +107,13 @@ type UseBoardGestureReturn = {
  * 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.
+ *
+ * v0.2.0 additions:
+ * - Rich callbacks (onPieceClick, onSquareClick, onPieceDragBegin, onPieceDragEnd)
+ * - Drag target square tracking (shared value for DragTargetHighlight)
+ * - Premove support (queue move when not your turn)
+ * - Haptic feedback via callback
+ * - Long press detection for onSquareLongPress
  */
 export function useBoardGesture({
   squareSize,
@@ -60,8 +123,12 @@ export function useBoardGesture({
   moveMethod,
   pieces,
   callbacks,
+  richCallbacks,
+  premoveCallbacks,
+  premovesEnabled = false,
   selectedSquare,
   legalMoves,
+  currentTurn,
 }: UseBoardGestureParams): UseBoardGestureReturn {
   // Shared values for drag tracking — updated on UI thread only
   const activeSquare = useSharedValue<string | null>(null);
@@ -69,6 +136,7 @@ export function useBoardGesture({
   const dragY = useSharedValue(0);
   const isDragging = useSharedValue(false);
   const dragPieceCode = useSharedValue<string | null>(null);
+  const dragTargetSquare = useSharedValue<string | null>(null);
 
   const gestureState: GestureState = {
     activeSquare,
@@ -76,6 +144,7 @@ export function useBoardGesture({
     dragY,
     isDragging,
     dragPieceCode,
+    dragTargetSquare,
   };
 
   // --- Refs for frequently-changing data (read from JS thread via runOnJS) ---
@@ -92,6 +161,18 @@ export function useBoardGesture({
   const callbacksRef = useRef(callbacks);
   callbacksRef.current = callbacks;
 
+  const richCallbacksRef = useRef(richCallbacks);
+  richCallbacksRef.current = richCallbacks;
+
+  const premoveCallbacksRef = useRef(premoveCallbacks);
+  premoveCallbacksRef.current = premoveCallbacks;
+
+  const currentTurnRef = useRef(currentTurn);
+  currentTurnRef.current = currentTurn;
+
+  // Track the piece being dragged for rich drag-end callback
+  const draggedPieceRef = useRef<{ square: string; code: PieceCode } | null>(null);
+
   // --- JS-thread bridge functions called from worklets via runOnJS ---
   // These read current values from refs, so they always have fresh data.
 
@@ -101,14 +182,21 @@ export function useBoardGesture({
     const currentSelected = selectedSquareRef.current;
     const currentLegalMoves = legalMovesRef.current;
     const cbs = callbacksRef.current;
+    const rich = richCallbacksRef.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
+      ? player === 'both' || pieceColorToPlayer(piece.color) === player
       : false;
 
+    // Check if it's this piece's turn (for premove detection)
+    const turn = currentTurnRef.current;
+    const isOwnTurn = piece && turn
+      ? isPieceTurn(piece.color, turn)
+      : true; // default to true if turn not tracked
+
     // 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)) {
@@ -116,25 +204,93 @@ export function useBoardGesture({
       activeSquare.value = null;
       isDragging.value = false;
       dragPieceCode.value = null;
+      dragTargetSquare.value = null;
+      rich?.onHaptic?.('move');
       return;
     }
 
     if (isPlayerPiece && piece) {
-      // Tapped/started dragging a player piece
+      // Premove: player piece but not their turn
+      if (premovesEnabled && !isOwnTurn) {
+        // If there's already a selected square, this tap completes a premove
+        if (currentSelected && currentSelected !== square) {
+          premoveCallbacksRef.current?.onPremoveSet?.({
+            from: currentSelected,
+            to: square,
+          });
+          cbs.onSelectionCleared();
+          activeSquare.value = null;
+          dragPieceCode.value = null;
+          dragTargetSquare.value = null;
+          return;
+        }
+        // First tap: select the piece for premove
+        activeSquare.value = square;
+        dragX.value = touchX;
+        dragY.value = touchY;
+        dragPieceCode.value = piece.code;
+        cbs.onPieceSelected(square);
+        rich?.onPieceClick?.(square, piece.code as PieceCode);
+        rich?.onHaptic?.('select');
+        return;
+      }
+
+      // Normal case: tapped/started dragging a player piece on their turn
       activeSquare.value = square;
       dragX.value = touchX;
       dragY.value = touchY;
       dragPieceCode.value = piece.code;
+      draggedPieceRef.current = { square, code: piece.code as PieceCode };
       cbs.onPieceSelected(square);
+
+      // Rich callbacks
+      rich?.onPieceClick?.(square, piece.code as PieceCode);
+      rich?.onHaptic?.('select');
     } else {
-      // Tapped empty square or opponent piece — clear selection
+      // Tapped empty square or opponent piece
+
+      // If premoves enabled and there's a selection, check if this is a premove target
+      if (premovesEnabled && currentSelected && !isOwnTurn) {
+        premoveCallbacksRef.current?.onPremoveSet?.({
+          from: currentSelected,
+          to: square,
+        });
+        cbs.onSelectionCleared();
+        activeSquare.value = null;
+        dragPieceCode.value = null;
+        dragTargetSquare.value = null;
+        return;
+      }
+
       activeSquare.value = null;
       dragPieceCode.value = null;
+      dragTargetSquare.value = null;
       if (currentSelected) {
         cbs.onSelectionCleared();
       }
+
+      // Rich callback: square click (empty square or opponent piece)
+      rich?.onSquareClick?.(square);
     }
-  }, [squareSize, orientation, player, moveMethod, activeSquare, dragX, dragY, isDragging, dragPieceCode]);
+  }, [squareSize, orientation, player, moveMethod, premovesEnabled, activeSquare, dragX, dragY, isDragging, dragPieceCode, dragTargetSquare]);
+
+  const handleDragStart = useCallback((touchX: number, touchY: number) => {
+    const rich = richCallbacksRef.current;
+    const dragged = draggedPieceRef.current;
+    if (dragged) {
+      rich?.onPieceDragBegin?.(dragged.square, dragged.code);
+    }
+    // Update drag target to current square
+    const square = xyToSquare(touchX, touchY, squareSize, orientation);
+    dragTargetSquare.value = square;
+  }, [squareSize, orientation, dragTargetSquare]);
+
+  const handleDragUpdate = useCallback((touchX: number, touchY: number) => {
+    // Update drag target square (for highlight). This runs on JS thread
+    // but is called from worklet via runOnJS only when the square changes.
+    const square = xyToSquare(touchX, touchY, squareSize, orientation);
+    dragTargetSquare.value = square;
+  }, [squareSize, orientation, dragTargetSquare]);
 
   const handleEnd = useCallback((touchX: number, touchY: number) => {
     const fromSquare = activeSquare.value;
@@ -142,18 +298,50 @@ export function useBoardGesture({
 
     const toSquare = xyToSquare(touchX, touchY, squareSize, orientation);
     isDragging.value = false;
+    dragTargetSquare.value = null;
+
+    const rich = richCallbacksRef.current;
+
+    // Fire drag end callback
+    const dragged = draggedPieceRef.current;
+    if (dragged) {
+      rich?.onPieceDragEnd?.(toSquare, dragged.code);
+      draggedPieceRef.current = null;
+    }
 
     if (fromSquare !== toSquare) {
-      callbacksRef.current.onPieceMoved(fromSquare, toSquare);
+      // Check if this is a premove (not your turn)
+      const turn = currentTurnRef.current;
+      const piece = piecesRef.current.find((p) => p.square === fromSquare);
+      const isOwnTurn = piece && turn ? isPieceTurn(piece.color, turn) : true;
+
+      if (premovesEnabled && !isOwnTurn) {
+        premoveCallbacksRef.current?.onPremoveSet?.({
+          from: fromSquare,
+          to: toSquare,
+        });
+      } else {
+        callbacksRef.current.onPieceMoved(fromSquare, toSquare);
+      }
     }
 
     activeSquare.value = null;
     dragPieceCode.value = null;
-  }, [squareSize, orientation, activeSquare, isDragging, dragPieceCode]);
+  }, [squareSize, orientation, activeSquare, isDragging, dragPieceCode, dragTargetSquare, premovesEnabled]);
+
+  // Long press handler (separate gesture, composed with pan)
+  const handleLongPress = useCallback((touchX: number, touchY: number) => {
+    const square = xyToSquare(touchX, touchY, squareSize, orientation);
+    richCallbacksRef.current?.onSquareLongPress?.(square);
+  }, [squareSize, orientation]);
 
   // --- Build the gesture (STABLE — only changes on layout/config changes) ---
   const canDrag = moveMethod !== 'click';
 
+  // Track the last drag target square to avoid redundant runOnJS calls
+  const lastDragTargetCol = useSharedValue(-1);
+  const lastDragTargetRow = useSharedValue(-1);
+
   const gesture = useMemo(() => {
     return Gesture.Pan()
       .enabled(gestureEnabled)
@@ -163,10 +351,11 @@ export function useBoardGesture({
         // Bridge to JS for piece lookup + selection logic
         runOnJS(handleBegin)(e.x, e.y);
       })
-      .onStart(() => {
+      .onStart((e) => {
         'worklet';
         if (!canDrag || !activeSquare.value) return;
         isDragging.value = true;
+        runOnJS(handleDragStart)(e.x, e.y);
       })
       .onUpdate((e) => {
         'worklet';
@@ -174,6 +363,15 @@ export function useBoardGesture({
         // Only 2 shared value writes — no JS bridge, no re-renders
         dragX.value = e.x;
         dragY.value = e.y;
+
+        // Update drag target square (only when square changes to minimize JS bridge calls)
+        const col = Math.max(0, Math.min(7, Math.floor(e.x / squareSize)));
+        const row = Math.max(0, Math.min(7, Math.floor(e.y / squareSize)));
+        if (col !== lastDragTargetCol.value || row !== lastDragTargetRow.value) {
+          lastDragTargetCol.value = col;
+          lastDragTargetRow.value = row;
+          runOnJS(handleDragUpdate)(e.x, e.y);
+        }
       })
       .onEnd((e) => {
         'worklet';
@@ -184,18 +382,31 @@ export function useBoardGesture({
         'worklet';
         // Safety reset if gesture was interrupted
         isDragging.value = false;
+        dragTargetSquare.value = null;
+        lastDragTargetCol.value = -1;
+        lastDragTargetRow.value = -1;
       });
   }, [
     gestureEnabled,
     canDrag,
+    squareSize,
     handleBegin,
+    handleDragStart,
+    handleDragUpdate,
     handleEnd,
     // Shared values are stable refs — listed for exhaustive-deps but don't cause recreations
     activeSquare,
     dragX,
     dragY,
     isDragging,
+    dragTargetSquare,
+    lastDragTargetCol,
+    lastDragTargetRow,
   ]);
 
+  // Compose with long press if the consumer wants it
+  // For now, long press is detected via a separate gesture that runs simultaneously.
+  // This is done at the board level if needed — keeping the pan gesture clean here.
+
   return { gesture, gestureState };
 }

package/src/use-premove.ts

@@ -0,0 +1,59 @@
+import { useState, useCallback } from 'react';
+
+import type { PremoveData } from './types';
+
+type UsePremoveReturn = {
+  /** The currently queued premove (only one at a time, like lichess) */
+  premove: PremoveData | null;
+  /** Queue a premove. Replaces any existing premove. */
+  setPremove: (premove: PremoveData) => void;
+  /** Clear the queued premove */
+  clearPremove: () => void;
+  /**
+   * Try to execute the queued premove.
+   * Returns the premove if one was queued (so the caller can apply it),
+   * then clears the queue. Returns null if no premove was queued.
+   */
+  consumePremove: () => PremoveData | null;
+};
+
+/**
+ * Manages a single premove queue (one premove at a time).
+ *
+ * Premoves work like lichess:
+ * 1. When it's not your turn, you can drag/click a move — it queues as a premove
+ * 2. The premove squares are highlighted with a distinct color
+ * 3. When your turn begins (FEN changes and it's now your turn), the premove
+ *    is automatically attempted via the board's internal chess.js
+ * 4. If the premove is legal, it's applied; if not, it's silently discarded
+ *
+ * The board.tsx orchestrates this: it calls consumePremove() in a useEffect
+ * that watches the FEN (turn change), then attempts the move.
+ */
+export function usePremove(): UsePremoveReturn {
+  const [premove, setPremoveState] = useState<PremoveData | null>(null);
+
+  const setPremove = useCallback((pm: PremoveData) => {
+    setPremoveState(pm);
+  }, []);
+
+  const clearPremove = useCallback(() => {
+    setPremoveState(null);
+  }, []);
+
+  const consumePremove = useCallback((): PremoveData | null => {
+    let consumed: PremoveData | null = null;
+    setPremoveState((current) => {
+      consumed = current;
+      return null;
+    });
+    return consumed;
+  }, []);
+
+  return {
+    premove,
+    setPremove,
+    clearPremove,
+    consumePremove,
+  };
+}