@react-chess-tools/react-chess-game 0.5.2 → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+import * as React$1 from 'react';
+import React__default, { CSSProperties } from 'react';
+import { ChessboardOptions } from 'react-chessboard';
+import * as chess_js from 'chess.js';
+import { Color, Chess } from 'chess.js';
+
+type Sound = "check" | "move" | "capture" | "gameOver";
+type Sounds = Record<Sound, HTMLAudioElement>;
+
+/**
+ * Props for the Sounds component
+ *
+ * Note: This is a logic-only component that returns null and does not render
+ * any DOM elements. It sets up board sounds via the useBoardSounds hook.
+ * Therefore, it does not accept HTML attributes like className, style, etc.
+ */
+type SoundsProps = {
+    sounds?: Partial<Record<Sound, string>>;
+};
+
+interface ChessGameProps extends React__default.HTMLAttributes<HTMLDivElement> {
+    options?: ChessboardOptions;
+}
+
+/**
+ * Board appearance configuration - colors for light and dark squares
+ */
+interface BoardTheme {
+    /** Style for light squares */
+    lightSquare: CSSProperties;
+    /** Style for dark squares */
+    darkSquare: CSSProperties;
+}
+/**
+ * Game state highlight colors (RGBA color strings)
+ */
+interface StateTheme {
+    /** Background color for last move from/to squares */
+    lastMove: string;
+    /** Background color for king when in check */
+    check: string;
+    /** Background color for currently selected piece's square */
+    activeSquare: string;
+    /** Full CSSProperties for valid drop target squares */
+    dropSquare: CSSProperties;
+}
+/**
+ * Move indicator styling - colors for move dots and capture rings
+ */
+interface IndicatorTheme {
+    /** Color for move dots on empty destination squares (used in radial-gradient) */
+    move: string;
+    /** Color for capture rings on capturable pieces (used in radial-gradient) */
+    capture: string;
+}
+/**
+ * Complete theme configuration for ChessGame component
+ */
+interface ChessGameTheme {
+    board: BoardTheme;
+    state: StateTheme;
+    indicators: IndicatorTheme;
+}
+/**
+ * Utility type for creating partial versions of nested objects
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Partial theme for user customization - allows overriding only specific properties
+ */
+type PartialChessGameTheme = DeepPartial<ChessGameTheme>;
+
+interface RootProps {
+    fen?: string;
+    orientation?: Color;
+    /** Optional theme configuration. Supports partial themes - only override the colors you need. */
+    theme?: PartialChessGameTheme;
+}
+
+type useChessGameProps = {
+    fen?: string;
+    orientation?: Color;
+};
+declare const useChessGame: ({ fen, orientation: initialOrientation, }?: useChessGameProps) => {
+    game: Chess;
+    currentFen: string;
+    currentPosition: string;
+    orientation: Color;
+    currentMoveIndex: number;
+    isLatestMove: boolean;
+    info: {
+        turn: Color;
+        isPlayerTurn: boolean;
+        isOpponentTurn: boolean;
+        moveNumber: number;
+        lastMove: chess_js.Move | undefined;
+        isCheck: boolean;
+        isCheckmate: boolean;
+        isDraw: boolean;
+        isStalemate: boolean;
+        isThreefoldRepetition: boolean;
+        isInsufficientMaterial: boolean;
+        isGameOver: boolean;
+        isDrawn: boolean;
+        hasPlayerWon: boolean;
+        hasPlayerLost: boolean;
+    };
+    methods: {
+        makeMove: (move: Parameters<Chess["move"]>[0]) => boolean;
+        setPosition: (fen: string, orientation: Color) => void;
+        flipBoard: () => void;
+        goToMove: (moveIndex: number) => void;
+        goToStart: () => void;
+        goToEnd: () => void;
+        goToPreviousMove: () => void;
+        goToNextMove: () => void;
+    };
+};
+
+declare const useChessGameContext: () => {
+    game: chess_js.Chess;
+    currentFen: string;
+    currentPosition: string;
+    orientation: chess_js.Color;
+    currentMoveIndex: number;
+    isLatestMove: boolean;
+    info: {
+        turn: chess_js.Color;
+        isPlayerTurn: boolean;
+        isOpponentTurn: boolean;
+        moveNumber: number;
+        lastMove: chess_js.Move | undefined;
+        isCheck: boolean;
+        isCheckmate: boolean;
+        isDraw: boolean;
+        isStalemate: boolean;
+        isThreefoldRepetition: boolean;
+        isInsufficientMaterial: boolean;
+        isGameOver: boolean;
+        isDrawn: boolean;
+        hasPlayerWon: boolean;
+        hasPlayerLost: boolean;
+    };
+    methods: {
+        makeMove: (move: Parameters<chess_js.Chess["move"]>[0]) => boolean;
+        setPosition: (fen: string, orientation: chess_js.Color) => void;
+        flipBoard: () => void;
+        goToMove: (moveIndex: number) => void;
+        goToStart: () => void;
+        goToEnd: () => void;
+        goToPreviousMove: () => void;
+        goToNextMove: () => void;
+    };
+};
+type ChessGameContextType = ReturnType<typeof useChessGame>;
+
+/**
+ * Props for the KeyboardControls component
+ *
+ * Note: This is a logic-only component that returns null and does not render
+ * any DOM elements. It sets up keyboard controls via the useKeyboardControls hook.
+ * Therefore, it does not accept HTML attributes like className, style, etc.
+ */
+type KeyboardControlsProps = {
+    controls?: KeyboardControls;
+};
+type KeyboardControls = Record<string, (context: ChessGameContextType) => void>;
+declare const KeyboardControls: React.FC<KeyboardControlsProps>;
+
+declare const ChessGame: {
+    Root: React$1.FC<React$1.PropsWithChildren<RootProps>>;
+    Board: React$1.ForwardRefExoticComponent<ChessGameProps & React$1.RefAttributes<HTMLDivElement>>;
+    Sounds: React$1.FC<SoundsProps>;
+    KeyboardControls: React$1.FC<{
+        controls?: KeyboardControls;
+    }>;
+};
+
+/**
+ * Returns an object with information about the current state of the game. This can be determined
+ * using chess.js instance, but this function is provided for convenience.
+ * @param game - The Chess.js instance representing the game.
+ * @returns An object with information about the current state of the game.
+ */
+declare const getGameInfo: (game: Chess, orientation: Color) => {
+    turn: Color;
+    isPlayerTurn: boolean;
+    isOpponentTurn: boolean;
+    moveNumber: number;
+    lastMove: chess_js.Move | undefined;
+    isCheck: boolean;
+    isCheckmate: boolean;
+    isDraw: boolean;
+    isStalemate: boolean;
+    isThreefoldRepetition: boolean;
+    isInsufficientMaterial: boolean;
+    isGameOver: boolean;
+    isDrawn: boolean;
+    hasPlayerWon: boolean;
+    hasPlayerLost: boolean;
+};
+type GameInfo = ReturnType<typeof getGameInfo>;
+
+/**
+ * Smart deep merge for ChessboardOptions that handles different property types appropriately:
+ * - Functions: Overwrite (custom functions replace base functions)
+ * - Objects: Deep merge (nested objects merge recursively)
+ * - Primitives: Overwrite (custom values replace base values)
+ *
+ * This ensures that computed options (like squareStyles with move highlighting) are preserved
+ * while allowing custom options to extend or override them intelligently.
+ *
+ * @param baseOptions - The computed base options (e.g., computed squareStyles, event handlers)
+ * @param customOptions - Custom options provided by the user
+ * @returns Intelligently merged ChessboardOptions
+ */
+declare const deepMergeChessboardOptions: (baseOptions: ChessboardOptions, customOptions?: Partial<ChessboardOptions>) => ChessboardOptions;
+
+/**
+ * Default theme for ChessGame component.
+ * These values match the original hardcoded colors for backward compatibility.
+ */
+declare const defaultGameTheme: ChessGameTheme;
+
+/**
+ * Lichess-inspired theme with green highlights
+ */
+declare const lichessTheme: ChessGameTheme;
+/**
+ * Chess.com-inspired theme with green board and yellow highlights
+ */
+declare const chessComTheme: ChessGameTheme;
+
+/**
+ * Deep merges a partial theme with the default theme.
+ * Allows users to override only specific theme properties while keeping defaults for the rest.
+ *
+ * @param partialTheme - Partial theme with only the properties to override
+ * @returns Complete theme with overridden properties merged with defaults
+ *
+ * @example
+ * ```typescript
+ * const customTheme = mergeTheme({
+ *   state: { lastMove: "rgba(100, 200, 100, 0.6)" }
+ * });
+ * // Returns full theme with only lastMove color changed
+ * ```
+ */
+declare const mergeTheme: (partialTheme?: PartialChessGameTheme) => ChessGameTheme;
+/**
+ * Deep merges a partial theme with a base theme.
+ * Useful when extending an existing theme.
+ *
+ * @param baseTheme - The base theme to extend
+ * @param partialTheme - Partial theme with properties to override
+ * @returns Complete theme with overridden properties
+ */
+declare const mergeThemeWith: (baseTheme: ChessGameTheme, partialTheme?: PartialChessGameTheme) => ChessGameTheme;
+
+/**
+ * Context for ChessGame theme
+ */
+declare const ChessGameThemeContext: React__default.Context<ChessGameTheme>;
+/**
+ * Hook to access the current ChessGame theme.
+ * Returns the default theme if no ThemeProvider is present.
+ */
+declare const useChessGameTheme: () => ChessGameTheme;
+
+declare const themes: {
+    readonly default: ChessGameTheme;
+    readonly lichess: ChessGameTheme;
+    readonly chessCom: ChessGameTheme;
+};
+
+export { type BoardTheme, ChessGame, type ChessGameContextType, type ChessGameProps, type ChessGameTheme, ChessGameThemeContext, type DeepPartial, type GameInfo, type IndicatorTheme, KeyboardControls, type PartialChessGameTheme, type RootProps, type Sound, type Sounds, type SoundsProps, type StateTheme, chessComTheme, deepMergeChessboardOptions, defaultGameTheme, lichessTheme, mergeTheme, mergeThemeWith, themes, useChessGame, useChessGameContext, type useChessGameProps, useChessGameTheme };