react-native-chess-kit 0.1.0 → 0.2.0

package/src/board-annotations.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { View, Text } from 'react-native';
+
+import type { ChessColor, AnnotationData } from './types';
+import { squareToXY } from './use-board-pieces';
+import { DEFAULT_ANNOTATION_BG, DEFAULT_ANNOTATION_TEXT, ANNOTATION_SCALE } from './constants';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+type BoardAnnotationsProps = {
+  boardSize: number;
+  orientation: ChessColor;
+  squareSize: number;
+  annotations: AnnotationData[];
+};
+
+// ---------------------------------------------------------------------------
+// Annotations layer
+// ---------------------------------------------------------------------------
+
+/**
+ * Text annotation badges on chess squares (!, ?, !!, ??, etc.).
+ *
+ * Each annotation appears as a small colored badge at the top-right
+ * corner of the target square. Positioned absolutely, pointer-events none.
+ */
+export const BoardAnnotations = React.memo(function BoardAnnotations({
+  boardSize,
+  orientation,
+  squareSize,
+  annotations,
+}: BoardAnnotationsProps) {
+  if (annotations.length === 0) return null;
+
+  const badgeSize = squareSize * ANNOTATION_SCALE;
+  const fontSize = badgeSize * 0.65;
+
+  return (
+    <View
+      style={{ position: 'absolute', width: boardSize, height: boardSize }}
+      pointerEvents="none"
+    >
+      {annotations.map((ann, i) => {
+        const { x, y } = squareToXY(ann.square, squareSize, orientation);
+        const bgColor = ann.backgroundColor ?? DEFAULT_ANNOTATION_BG;
+        const textColor = ann.color ?? DEFAULT_ANNOTATION_TEXT;
+
+        return (
+          <View
+            key={`ann-${ann.square}-${i}`}
+            style={{
+              position: 'absolute',
+              // Position at top-right corner of the square
+              left: x + squareSize - badgeSize - 1,
+              top: y + 1,
+              minWidth: badgeSize,
+              height: badgeSize,
+              borderRadius: badgeSize / 2,
+              backgroundColor: bgColor,
+              alignItems: 'center',
+              justifyContent: 'center',
+              paddingHorizontal: 2,
+            }}
+          >
+            <Text
+              style={{
+                color: textColor,
+                fontSize,
+                fontWeight: '700',
+                lineHeight: badgeSize * 0.85,
+                textAlign: 'center',
+              }}
+              numberOfLines={1}
+            >
+              {ann.text}
+            </Text>
+          </View>
+        );
+      })}
+    </View>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Standalone export for advanced consumers
+// ---------------------------------------------------------------------------
+
+type AnnotationBadgeProps = {
+  square: string;
+  text: string;
+  squareSize: number;
+  orientation: ChessColor;
+  color?: string;
+  backgroundColor?: string;
+};
+
+/**
+ * Single annotation badge component.
+ * Exported for consumers who build their own overlay layers.
+ */
+export const Annotation = React.memo(function Annotation({
+  square,
+  text,
+  squareSize,
+  orientation,
+  color,
+  backgroundColor,
+}: AnnotationBadgeProps) {
+  const { x, y } = squareToXY(square, squareSize, orientation);
+  const badgeSize = squareSize * ANNOTATION_SCALE;
+  const fontSize = badgeSize * 0.65;
+  const bgColor = backgroundColor ?? DEFAULT_ANNOTATION_BG;
+  const textColor = color ?? DEFAULT_ANNOTATION_TEXT;
+
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        left: x + squareSize - badgeSize - 1,
+        top: y + 1,
+        minWidth: badgeSize,
+        height: badgeSize,
+        borderRadius: badgeSize / 2,
+        backgroundColor: bgColor,
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 2,
+      }}
+      pointerEvents="none"
+    >
+      <Text
+        style={{
+          color: textColor,
+          fontSize,
+          fontWeight: '700',
+          lineHeight: badgeSize * 0.85,
+          textAlign: 'center',
+        }}
+        numberOfLines={1}
+      >
+        {text}
+      </Text>
+    </View>
+  );
+});

package/src/board-arrows.tsx

@@ -0,0 +1,197 @@
+import React from 'react';
+import { View } from 'react-native';
+import Svg, { Line, Polygon, Circle as SvgCircle } from 'react-native-svg';
+
+import type { ChessColor, ArrowData, ShapeData } from './types';
+import {
+  DEFAULT_ARROW_COLOR,
+  DEFAULT_SHAPE_COLOR,
+  ARROW_STROKE_WIDTH,
+  ARROW_HEAD_SIZE,
+  ARROW_SHORTEN_BY,
+} from './constants';
+
+// ---------------------------------------------------------------------------
+// Coordinate utilities (percentage-based viewBox 0-100)
+// ---------------------------------------------------------------------------
+
+function squareToViewBoxCenter(
+  square: string,
+  orientation: ChessColor,
+): { x: number; y: number } {
+  const fileIdx = square.charCodeAt(0) - 97;
+  const rankIdx = parseInt(square[1], 10) - 1;
+  const col = orientation === 'white' ? fileIdx : 7 - fileIdx;
+  const row = orientation === 'white' ? 7 - rankIdx : rankIdx;
+  return {
+    x: (col + 0.5) * 12.5,
+    y: (row + 0.5) * 12.5,
+  };
+}
+
+function calculateArrowPath(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  shortenBy: number,
+): { x1: number; y1: number; x2: number; y2: number } {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.sqrt(dx * dx + dy * dy);
+  if (len === 0) return { x1: from.x, y1: from.y, x2: to.x, y2: to.y };
+
+  const ux = dx / len;
+  const uy = dy / len;
+  return {
+    x1: from.x + ux * shortenBy,
+    y1: from.y + uy * shortenBy,
+    x2: to.x - ux * shortenBy,
+    y2: to.y - uy * shortenBy,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+type BoardArrowsProps = {
+  boardSize: number;
+  orientation: ChessColor;
+  arrows?: ArrowData[];
+  shapes?: ShapeData[];
+};
+
+// ---------------------------------------------------------------------------
+// Combined arrows + shapes SVG layer
+// ---------------------------------------------------------------------------
+
+/**
+ * SVG overlay for arrows and shapes drawn on the board.
+ *
+ * Uses a percentage-based 100x100 viewBox so coordinates map cleanly
+ * to the 8x8 grid (each square = 12.5 x 12.5 units).
+ *
+ * Renders above the pieces layer so arrows are always visible.
+ */
+export const BoardArrows = React.memo(function BoardArrows({
+  boardSize,
+  orientation,
+  arrows,
+  shapes,
+}: BoardArrowsProps) {
+  const hasArrows = arrows && arrows.length > 0;
+  const hasShapes = shapes && shapes.length > 0;
+
+  if (!hasArrows && !hasShapes) return null;
+
+  return (
+    <View
+      style={{ position: 'absolute', width: boardSize, height: boardSize }}
+      pointerEvents="none"
+    >
+      <Svg viewBox="0 0 100 100" width={boardSize} height={boardSize}>
+        {/* Shapes (circles) -- drawn under arrows */}
+        {hasShapes &&
+          shapes.map((shape, i) => {
+            if (shape.type === 'circle') {
+              const center = squareToViewBoxCenter(shape.square, orientation);
+              const color = shape.color ?? DEFAULT_SHAPE_COLOR;
+              return (
+                <SvgCircle
+                  key={`circle-${shape.square}-${i}`}
+                  cx={center.x}
+                  cy={center.y}
+                  r={5.5}
+                  fill="none"
+                  stroke={color}
+                  strokeWidth={1.2}
+                  opacity={0.85}
+                />
+              );
+            }
+            return null;
+          })}
+
+        {/* Arrows */}
+        {hasArrows &&
+          arrows.map((arrow, i) => (
+            <ArrowSvg
+              key={`arrow-${arrow.from}-${arrow.to}-${i}`}
+              from={arrow.from}
+              to={arrow.to}
+              color={arrow.color ?? DEFAULT_ARROW_COLOR}
+              width={arrow.width ?? ARROW_STROKE_WIDTH}
+              orientation={orientation}
+            />
+          ))}
+      </Svg>
+    </View>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Single arrow SVG element
+// ---------------------------------------------------------------------------
+
+type ArrowSvgProps = {
+  from: string;
+  to: string;
+  color: string;
+  width: number;
+  orientation: ChessColor;
+};
+
+const ArrowSvg = React.memo(function ArrowSvg({
+  from,
+  to,
+  color,
+  width,
+  orientation,
+}: ArrowSvgProps) {
+  const fromCoord = squareToViewBoxCenter(from, orientation);
+  const toCoord = squareToViewBoxCenter(to, orientation);
+  const path = calculateArrowPath(fromCoord, toCoord, ARROW_SHORTEN_BY);
+
+  const dx = path.x2 - path.x1;
+  const dy = path.y2 - path.y1;
+  const len = Math.sqrt(dx * dx + dy * dy);
+
+  if (len === 0) return null;
+
+  const ux = dx / len;
+  const uy = dy / len;
+  const headSize = ARROW_HEAD_SIZE;
+
+  const tip = { x: path.x2, y: path.y2 };
+  const baseLeft = {
+    x: path.x2 - ux * headSize * 2 + uy * headSize,
+    y: path.y2 - uy * headSize * 2 - ux * headSize,
+  };
+  const baseRight = {
+    x: path.x2 - ux * headSize * 2 - uy * headSize,
+    y: path.y2 - uy * headSize * 2 + ux * headSize,
+  };
+
+  const arrowPoints = `${tip.x},${tip.y} ${baseLeft.x},${baseLeft.y} ${baseRight.x},${baseRight.y}`;
+
+  return (
+    <>
+      <Line
+        x1={path.x1}
+        y1={path.y1}
+        x2={path.x2}
+        y2={path.y2}
+        stroke={color}
+        strokeWidth={width}
+        strokeLinecap="round"
+        opacity={0.85}
+      />
+      <Polygon points={arrowPoints} fill={color} opacity={0.85} />
+    </>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Standalone exports for advanced consumers
+// ---------------------------------------------------------------------------
+
+export { ArrowSvg as Arrow };

package/src/board-highlights.tsx

@@ -0,0 +1,226 @@
+import React from 'react';
+import { View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+import type { ChessColor, HighlightData } from './types';
+import { squareToXY } from './use-board-pieces';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+type BoardHighlightsProps = {
+  boardSize: number;
+  orientation: ChessColor;
+  squareSize: number;
+  /** Last move squares to highlight */
+  lastMove?: { from: string; to: string } | null;
+  lastMoveColor: string;
+  /** Check highlight on king square (auto-detected) */
+  checkSquare?: string | null;
+  checkColor: string;
+  /** Selected piece square */
+  selectedSquare?: string | null;
+  selectedColor: string;
+  /** Premove squares */
+  premoveSquares?: { from: string; to: string } | null;
+  premoveColor: string;
+  /** Custom highlights from consumer */
+  highlights?: HighlightData[];
+  /** Imperative highlights (from ref.highlight()) */
+  imperativeHighlights?: HighlightData[];
+};
+
+type DragTargetHighlightProps = {
+  squareSize: number;
+  orientation: ChessColor;
+  dragTargetSquare: SharedValue<string | null>;
+  color: string;
+};
+
+// ---------------------------------------------------------------------------
+// Static highlights (View-based, no animation needed)
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders all board square highlights as a single layer.
+ *
+ * Combines multiple highlight sources (last move, check, selected piece,
+ * premoves, custom, and imperative) into one flat list of colored rectangles.
+ * Rendered between the background and pieces layers.
+ *
+ * Uses plain Views (not Animated) because highlights change discretely
+ * on move events, not during animation frames.
+ */
+export const BoardHighlights = React.memo(function BoardHighlights({
+  boardSize,
+  orientation,
+  squareSize,
+  lastMove,
+  lastMoveColor,
+  checkSquare,
+  checkColor,
+  selectedSquare,
+  selectedColor,
+  premoveSquares,
+  premoveColor,
+  highlights,
+  imperativeHighlights,
+}: BoardHighlightsProps) {
+  // Collect all highlights into a flat array (ordered by visual priority: bottom to top)
+  const allHighlights: HighlightData[] = [];
+
+  // Last move (lowest priority -- drawn first, underneath everything)
+  if (lastMove) {
+    allHighlights.push({ square: lastMove.from, color: lastMoveColor });
+    allHighlights.push({ square: lastMove.to, color: lastMoveColor });
+  }
+
+  // Premove highlights
+  if (premoveSquares) {
+    allHighlights.push({ square: premoveSquares.from, color: premoveColor });
+    allHighlights.push({ square: premoveSquares.to, color: premoveColor });
+  }
+
+  // Selected piece square
+  if (selectedSquare) {
+    allHighlights.push({ square: selectedSquare, color: selectedColor });
+  }
+
+  // Check indicator (king square)
+  if (checkSquare) {
+    allHighlights.push({ square: checkSquare, color: checkColor });
+  }
+
+  // Consumer-provided custom highlights
+  if (highlights) {
+    for (const h of highlights) {
+      allHighlights.push(h);
+    }
+  }
+
+  // Imperative highlights (from ref.highlight() calls)
+  if (imperativeHighlights) {
+    for (const h of imperativeHighlights) {
+      allHighlights.push(h);
+    }
+  }
+
+  if (allHighlights.length === 0) return null;
+
+  return (
+    <View
+      style={{ position: 'absolute', width: boardSize, height: boardSize }}
+      pointerEvents="none"
+    >
+      {allHighlights.map((h, i) => {
+        const { x, y } = squareToXY(h.square, squareSize, orientation);
+        return (
+          <View
+            key={`${h.square}-${h.color}-${i}`}
+            style={{
+              position: 'absolute',
+              left: x,
+              top: y,
+              width: squareSize,
+              height: squareSize,
+              backgroundColor: h.color,
+            }}
+          />
+        );
+      })}
+    </View>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Drag target highlight (Animated, updates on UI thread during drag)
+// ---------------------------------------------------------------------------
+
+/**
+ * Highlight on the square currently under the dragged piece.
+ * Uses Reanimated shared values for zero-JS-bridge updates during drag.
+ */
+export const DragTargetHighlight = React.memo(function DragTargetHighlight({
+  squareSize,
+  orientation,
+  dragTargetSquare,
+  color,
+}: DragTargetHighlightProps) {
+  const animatedStyle = useAnimatedStyle(() => {
+    const square = dragTargetSquare.value;
+    if (!square) {
+      return { opacity: 0, transform: [{ translateX: 0 }, { translateY: 0 }] };
+    }
+
+    // Inline coordinate calculation (worklet-safe, no function call)
+    const fileIdx = square.charCodeAt(0) - 97;
+    const rankIdx = parseInt(square[1], 10) - 1;
+    const col = orientation === 'white' ? fileIdx : 7 - fileIdx;
+    const row = orientation === 'white' ? 7 - rankIdx : rankIdx;
+
+    return {
+      opacity: 1,
+      transform: [
+        { translateX: col * squareSize },
+        { translateY: row * squareSize },
+      ],
+    };
+  });
+
+  return (
+    <Animated.View
+      style={[
+        {
+          position: 'absolute',
+          width: squareSize,
+          height: squareSize,
+          backgroundColor: color,
+        },
+        animatedStyle,
+      ]}
+      pointerEvents="none"
+    />
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Standalone SquareHighlight (exported for advanced consumers)
+// ---------------------------------------------------------------------------
+
+type SquareHighlightProps = {
+  square: string;
+  color: string;
+  squareSize: number;
+  orientation: ChessColor;
+};
+
+/**
+ * Single square highlight component.
+ * Exported for consumers who build their own overlay layers.
+ */
+export const SquareHighlight = React.memo(function SquareHighlight({
+  square,
+  color,
+  squareSize,
+  orientation,
+}: SquareHighlightProps) {
+  const { x, y } = squareToXY(square, squareSize, orientation);
+
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        left: x,
+        top: y,
+        width: squareSize,
+        height: squareSize,
+        backgroundColor: color,
+      }}
+      pointerEvents="none"
+    />
+  );
+});

package/src/board-piece.tsx

@@ -3,17 +3,24 @@ import Animated, {
   useAnimatedStyle,
   useSharedValue,
   withTiming,
+  withSpring,
+  FadeOut,
   type SharedValue,
 } from 'react-native-reanimated';
 
+import type { AnimationConfig } from './types';
+import { DEFAULT_MOVE_DURATION, CAPTURE_FADE_DURATION } from './constants';
+
 type BoardPieceProps = {
   /** Target pixel position (top-left of destination square) */
   targetX: number;
   targetY: number;
   /** Square size in pixels */
   squareSize: number;
-  /** Move animation duration in ms */
-  moveDuration: number;
+  /** Animation config for piece movement (timing or spring) */
+  animationConfig?: AnimationConfig;
+  /** Fallback move duration if animationConfig not provided */
+  moveDuration?: number;
   /** The piece visual (rendered by parent via renderPiece) */
   children: React.ReactElement;
   /** Gesture state: is this piece currently being dragged? */
@@ -23,6 +30,34 @@ type BoardPieceProps = {
   square: string;
 };
 
+/**
+ * Animate a shared value using the provided AnimationConfig.
+ * Falls back to withTiming with moveDuration for backwards compatibility.
+ */
+function animateValue(
+  target: number,
+  config?: AnimationConfig,
+  moveDuration?: number,
+): number {
+  if (config) {
+    if (config.type === 'spring') {
+      return withSpring(target, {
+        damping: config.damping ?? 15,
+        stiffness: config.stiffness ?? 200,
+        mass: config.mass ?? 1,
+      });
+    }
+    // timing
+    return withTiming(target, {
+      duration: config.duration ?? DEFAULT_MOVE_DURATION,
+    });
+  }
+
+  const duration = moveDuration ?? DEFAULT_MOVE_DURATION;
+  if (duration <= 0) return target;
+  return withTiming(target, { duration });
+}
+
 /**
  * A single animated chess piece.
  *
@@ -35,14 +70,18 @@ type BoardPieceProps = {
  * - No position changes on the original piece during drag
  *
  * After a move:
- * - Snaps to new position via withTiming on translateX/translateY
- * - Duration controlled by user's animation speed setting
+ * - Snaps to new position via withTiming/withSpring on translateX/translateY
+ * - Animation style controlled by user's animationConfig or moveDuration
+ *
+ * On capture (unmount):
+ * - Fades out via Reanimated's `exiting` prop (FadeOut)
  */
 export const BoardPieceView = React.memo(
   function BoardPieceView({
     targetX,
     targetY,
     squareSize,
+    animationConfig,
     moveDuration,
     children,
     activeSquare,
@@ -57,13 +96,9 @@ export const BoardPieceView = React.memo(
     // useEffect is the correct pattern for reacting to JS prop changes —
     // useDerivedValue is meant for shared-value-to-shared-value derivation.
     useEffect(() => {
-      currentX.value = moveDuration > 0
-        ? withTiming(targetX, { duration: moveDuration })
-        : targetX;
-      currentY.value = moveDuration > 0
-        ? withTiming(targetY, { duration: moveDuration })
-        : targetY;
-    }, [targetX, targetY, moveDuration, currentX, currentY]);
+      currentX.value = animateValue(targetX, animationConfig, moveDuration);
+      currentY.value = animateValue(targetY, animationConfig, moveDuration);
+    }, [targetX, targetY, animationConfig, moveDuration, currentX, currentY]);
 
     const animatedStyle = useAnimatedStyle(() => {
       const isBeingDragged = isDragging.value && activeSquare.value === square;
@@ -88,17 +123,20 @@ export const BoardPieceView = React.memo(
           },
           animatedStyle,
         ]}
+        // Fade out when this piece is captured (removed from the piece list)
+        exiting={FadeOut.duration(CAPTURE_FADE_DURATION)}
       >
         {children}
       </Animated.View>
     );
   },
-  // Custom comparator: only re-render when position or square changes
+  // Custom comparator: only re-render when position, square, or animation config changes
   (prev, next) =>
     prev.targetX === next.targetX &&
     prev.targetY === next.targetY &&
     prev.square === next.square &&
     prev.squareSize === next.squareSize &&
     prev.moveDuration === next.moveDuration &&
+    prev.animationConfig === next.animationConfig &&
     prev.children === next.children,
 );