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

package/src/theme/defaults.ts

@@ -0,0 +1,22 @@
+import type { ChessGameTheme } from "./types";
+
+/**
+ * Default theme for ChessGame component.
+ * These values match the original hardcoded colors for backward compatibility.
+ */
+export const defaultGameTheme: ChessGameTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#f0d9b5" },
+    darkSquare: { backgroundColor: "#b58863" },
+  },
+  state: {
+    lastMove: "rgba(255, 255, 0, 0.5)",
+    check: "rgba(255, 0, 0, 0.5)",
+    activeSquare: "rgba(255, 255, 0, 0.5)",
+    dropSquare: { backgroundColor: "rgba(255, 255, 0, 0.4)" },
+  },
+  indicators: {
+    move: "rgba(0, 0, 0, 0.1)",
+    capture: "rgba(1, 0, 0, 0.1)",
+  },
+};

package/src/theme/index.ts

@@ -0,0 +1,36 @@
+// Types
+export type {
+  ChessGameTheme,
+  BoardTheme,
+  StateTheme,
+  IndicatorTheme,
+  PartialChessGameTheme,
+  DeepPartial,
+} from "./types";
+
+// Default theme
+export { defaultGameTheme } from "./defaults";
+
+// Preset themes
+export { lichessTheme, chessComTheme } from "./presets";
+
+// All themes as a single object
+import { defaultGameTheme } from "./defaults";
+import { lichessTheme, chessComTheme } from "./presets";
+
+export const themes = {
+  default: defaultGameTheme,
+  lichess: lichessTheme,
+  chessCom: chessComTheme,
+} as const;
+
+// Utilities
+export { mergeTheme, mergeThemeWith } from "./utils";
+
+// Context and hook
+export {
+  ChessGameThemeContext,
+  useChessGameTheme,
+  ThemeProvider,
+} from "./context";
+export type { ThemeProviderProps } from "./context";

package/src/theme/presets.ts

@@ -0,0 +1,41 @@
+import type { ChessGameTheme } from "./types";
+
+/**
+ * Lichess-inspired theme with green highlights
+ */
+export const lichessTheme: ChessGameTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#f0d9b5" },
+    darkSquare: { backgroundColor: "#b58863" },
+  },
+  state: {
+    lastMove: "rgba(155, 199, 0, 0.41)",
+    check: "rgba(255, 0, 0, 0.5)",
+    activeSquare: "rgba(20, 85, 30, 0.5)",
+    dropSquare: { backgroundColor: "rgba(20, 85, 30, 0.3)" },
+  },
+  indicators: {
+    move: "rgba(20, 85, 30, 0.3)",
+    capture: "rgba(20, 85, 30, 0.3)",
+  },
+};
+
+/**
+ * Chess.com-inspired theme with green board and yellow highlights
+ */
+export const chessComTheme: ChessGameTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#ebecd0" },
+    darkSquare: { backgroundColor: "#779556" },
+  },
+  state: {
+    lastMove: "rgba(255, 255, 0, 0.5)",
+    check: "rgba(255, 0, 0, 0.7)",
+    activeSquare: "rgba(255, 255, 0, 0.5)",
+    dropSquare: { backgroundColor: "rgba(255, 255, 0, 0.4)" },
+  },
+  indicators: {
+    move: "rgba(0, 0, 0, 0.1)",
+    capture: "rgba(0, 0, 0, 0.1)",
+  },
+};

package/src/theme/types.ts

@@ -0,0 +1,56 @@
+import { CSSProperties } from "react";
+
+/**
+ * Board appearance configuration - colors for light and dark squares
+ */
+export interface BoardTheme {
+  /** Style for light squares */
+  lightSquare: CSSProperties;
+  /** Style for dark squares */
+  darkSquare: CSSProperties;
+}
+
+/**
+ * Game state highlight colors (RGBA color strings)
+ */
+export 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
+ */
+export 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
+ */
+export interface ChessGameTheme {
+  board: BoardTheme;
+  state: StateTheme;
+  indicators: IndicatorTheme;
+}
+
+/**
+ * Utility type for creating partial versions of nested objects
+ */
+export 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
+ */
+export type PartialChessGameTheme = DeepPartial<ChessGameTheme>;

package/src/theme/utils.ts

@@ -0,0 +1,47 @@
+import { merge } from "lodash";
+import type { ChessGameTheme, PartialChessGameTheme } from "./types";
+import { defaultGameTheme } from "./defaults";
+
+/**
+ * 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
+ * ```
+ */
+export const mergeTheme = (
+  partialTheme?: PartialChessGameTheme,
+): ChessGameTheme => {
+  if (!partialTheme) {
+    return { ...defaultGameTheme };
+  }
+
+  return merge({}, defaultGameTheme, partialTheme);
+};
+
+/**
+ * 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
+ */
+export const mergeThemeWith = (
+  baseTheme: ChessGameTheme,
+  partialTheme?: PartialChessGameTheme,
+): ChessGameTheme => {
+  if (!partialTheme) {
+    return { ...baseTheme };
+  }
+
+  return merge({}, baseTheme, partialTheme);
+};

package/src/utils/__tests__/board.test.ts

@@ -1,6 +1,8 @@
 import { Chess } from "chess.js";
 import { getCustomSquareStyles, deepMergeChessboardOptions } from "../board";
 import { getGameInfo } from "../chess";
+import { defaultGameTheme } from "../../theme/defaults";
+import type { ChessGameTheme } from "../../theme/types";
 
 describe("Board Utilities", () => {
   describe("getCustomSquareStyles", () => {
@@ -139,6 +141,122 @@ describe("Board Utilities", () => {
       expect(styles.a3.background).toContain("25%");
       expect(styles.c3.background).toContain("25%");
     });
+
+    describe("with custom theme", () => {
+      const customTheme: ChessGameTheme = {
+        ...defaultGameTheme,
+        state: {
+          ...defaultGameTheme.state,
+          lastMove: "rgba(100, 200, 100, 0.6)",
+          check: "rgba(200, 50, 50, 0.7)",
+          activeSquare: "rgba(100, 100, 255, 0.5)",
+        },
+        indicators: {
+          move: "rgba(50, 50, 50, 0.2)",
+          capture: "rgba(200, 50, 50, 0.3)",
+        },
+      };
+
+      it("should use custom theme colors for last move", () => {
+        const game = new Chess();
+        game.move("e4");
+        const orientation = "w";
+        const info = getGameInfo(game, orientation);
+        const activeSquare = null;
+
+        const styles = getCustomSquareStyles(
+          game,
+          info,
+          activeSquare,
+          customTheme,
+        );
+
+        expect(styles.e2).toHaveProperty(
+          "backgroundColor",
+          "rgba(100, 200, 100, 0.6)",
+        );
+        expect(styles.e4).toHaveProperty(
+          "backgroundColor",
+          "rgba(100, 200, 100, 0.6)",
+        );
+      });
+
+      it("should use custom theme colors for active square", () => {
+        const game = new Chess();
+        const orientation = "w";
+        const info = getGameInfo(game, orientation);
+        const activeSquare = "e2";
+
+        const styles = getCustomSquareStyles(
+          game,
+          info,
+          activeSquare,
+          customTheme,
+        );
+
+        expect(styles.e2).toHaveProperty(
+          "backgroundColor",
+          "rgba(100, 100, 255, 0.5)",
+        );
+      });
+
+      it("should use custom theme colors for check", () => {
+        const game = new Chess(
+          "rnbqkbnr/ppp2ppp/8/3pp3/4P3/5Q2/PPPP1PPP/RNB1KBNR b KQkq - 1 3",
+        );
+        const orientation = "b";
+        const info = getGameInfo(game, orientation);
+        const modifiedInfo = { ...info, isCheck: true };
+        const activeSquare = null;
+
+        const styles = getCustomSquareStyles(
+          game,
+          modifiedInfo,
+          activeSquare,
+          customTheme,
+        );
+
+        expect(styles.e8).toHaveProperty(
+          "backgroundColor",
+          "rgba(200, 50, 50, 0.7)",
+        );
+      });
+
+      it("should use custom theme colors for move indicators", () => {
+        const game = new Chess();
+        const orientation = "w";
+        const info = getGameInfo(game, orientation);
+        const activeSquare = "e2";
+
+        const styles = getCustomSquareStyles(
+          game,
+          info,
+          activeSquare,
+          customTheme,
+        );
+
+        expect(styles.e3.background).toContain("rgba(50, 50, 50, 0.2)");
+        expect(styles.e4.background).toContain("rgba(50, 50, 50, 0.2)");
+      });
+
+      it("should use custom theme colors for capture indicators", () => {
+        const game = new Chess(
+          "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2",
+        );
+        const orientation = "w";
+        const info = getGameInfo(game, orientation);
+        const activeSquare = "e4";
+
+        const styles = getCustomSquareStyles(
+          game,
+          info,
+          activeSquare,
+          customTheme,
+        );
+
+        expect(styles.d5.background).toContain("rgba(200, 50, 50, 0.3)");
+      });
+    });
   });
 
   describe("deepMergeChessboardOptions", () => {

package/src/utils/board.ts

@@ -3,14 +3,23 @@ import { type CSSProperties } from "react";
 import { merge } from "lodash";
 import type { ChessboardOptions } from "react-chessboard";
 import { getDestinationSquares, type GameInfo } from "./chess";
+import type { ChessGameTheme } from "../theme/types";
+import { defaultGameTheme } from "../theme/defaults";
 
-const LAST_MOVE_COLOR = "rgba(255, 255, 0, 0.5)";
-const CHECK_COLOR = "rgba(255, 0, 0, 0.5)";
-
+/**
+ * Generates custom square styles based on game state and theme.
+ *
+ * @param game - Chess.js game instance
+ * @param info - Game info containing lastMove, isCheck, turn
+ * @param activeSquare - Currently selected square (if any)
+ * @param theme - Theme configuration (defaults to defaultGameTheme)
+ * @returns Record of square names to CSS properties
+ */
 export const getCustomSquareStyles = (
   game: Chess,
   info: GameInfo,
   activeSquare: Square | null,
+  theme: ChessGameTheme = defaultGameTheme,
 ) => {
   const customSquareStyles: Record<string, CSSProperties> = {};
 
@@ -18,16 +27,16 @@ export const getCustomSquareStyles = (
 
   if (lastMove) {
     customSquareStyles[lastMove.from] = {
-      backgroundColor: LAST_MOVE_COLOR,
+      backgroundColor: theme.state.lastMove,
     };
     customSquareStyles[lastMove.to] = {
-      backgroundColor: LAST_MOVE_COLOR,
+      backgroundColor: theme.state.lastMove,
     };
   }
 
   if (activeSquare) {
     customSquareStyles[activeSquare] = {
-      backgroundColor: LAST_MOVE_COLOR,
+      backgroundColor: theme.state.activeSquare,
     };
   }
 
@@ -37,8 +46,8 @@ export const getCustomSquareStyles = (
       customSquareStyles[square] = {
         background:
           game.get(square) && game.get(square)?.color !== turn
-            ? "radial-gradient(circle, rgba(1, 0, 0, 0.1) 85%, transparent 85%)"
-            : "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)",
+            ? `radial-gradient(circle, ${theme.indicators.capture} 85%, transparent 85%)`
+            : `radial-gradient(circle, ${theme.indicators.move} 25%, transparent 25%)`,
       };
     });
   }
@@ -48,7 +57,7 @@ export const getCustomSquareStyles = (
       return row.forEach((square) => {
         if (square?.type === "k" && square?.color === info.turn) {
           customSquareStyles[square.square] = {
-            backgroundColor: CHECK_COLOR,
+            backgroundColor: theme.state.check,
           };
         }
       });

package/src/utils/chess.ts

@@ -8,9 +8,17 @@ import _ from "lodash";
  * @returns A new Chess.js instance with the same state as the original.
  */
 export const cloneGame = (game: Chess) => {
-  const copy = new Chess();
-  copy.loadPgn(game.pgn());
-  return copy;
+  try {
+    const copy = new Chess();
+    const pgn = game?.pgn();
+    if (pgn) {
+      copy.loadPgn(pgn);
+    }
+    return copy;
+  } catch (e) {
+    console.error("Failed to clone game:", e);
+    return new Chess();
+  }
 };
 
 /**
@@ -74,6 +82,10 @@ export const requiresPromotion = (
   game: Chess,
   move: Parameters<Chess["move"]>[0],
 ) => {
+  if (!game) {
+    throw new Error("Game is required");
+  }
+
   try {
     const copy = cloneGame(game);
     const result = copy.move(move);
@@ -100,13 +112,21 @@ export const getCurrentFen = (
   const tempGame = new Chess();
   if (currentMoveIndex === -1) {
     if (fen) {
-      tempGame.load(fen);
+      try {
+        tempGame.load(fen);
+      } catch (e) {
+        console.error("Failed to load FEN in getCurrentFen:", fen, e);
+      }
     }
   } else {
     const moves = game.history().slice(0, currentMoveIndex + 1);
 
     if (fen) {
-      tempGame.load(fen);
+      try {
+        tempGame.load(fen);
+      } catch (e) {
+        console.error("Failed to load FEN in getCurrentFen:", fen, e);
+      }
     }
     moves.forEach((move) => tempGame.move(move));
   }

package/README.MD

@@ -1,190 +0,0 @@
-<div align="center">
-  <p>
-
-  </p>
-  <p>
-    <a href="https://github.com/Clariity/react-chessboard" target="blank">react-chessboard</a> + <a href="https://github.com/jhlywa/chess.js" target="blank">chess.js</a> + nice defaults
-    </p>
-    <p>
-    An easy-customizable, ready-to-use chess game component for React.
-</div>
-
-## Project Description
-
-This project is a React-based chess game that allows users to play chess online. It is part of the `react-chess-tools` package and is designed to be easy to use and customizable. It is built on top of the `react-chessboard` and `chess.js` packages, and provides a nice default configuration for the chess game, including:
-
-- Sounds
-- Move-by-click
-- Square highlighting
-- Keyboard controls
-
-It is built using an approach similar to the one used in the `radix-ui`, where the `ChessGame` component is built using a `ChessGameContext` that you can use to customize and enhance the component game. It also provides a set of default components that you can use to build your next chess app.
-
-## Preview
-
-Visit the [demo](https://react-chess-tools.vercel.app/) to see the `react-chess-game` component in action.
-
-## Installation
-
-To install the `react-chess-game` package, run the following command:
-
-```bash
-$ npm install @react-chess-tools/react-chess-game
-```
-
-## Usage
-
-To use the `react-chess-game` package, you can import the `ChessGame` component and use it as follows:
-
-```tsx
-import { ChessGame } from "@react-chess-tools/react-chess-game";
-
-const App = () => (
-  <ChessGame.Root>
-    <ChessGame.Board />
-  </ChessGame.Root>
-);
-```
-
-## Documentation
-
-The `react-chess-game` package provides a set of components that you can use to build your chess app. The following sections describe the components and their usage.
-
-### ChessGame.Root
-
-The `ChessGame.Root` component is the root component of the `react-chess-game` package. It is used to provide the `ChessGameContext` to the rest of the components. It also provides a set of default values for the `ChessGameContext` that you can customize. It instantiates a `Chess` instance using the `fen` prop and provides it to the `ChessGameContext`.
-
-#### Props
-
-The `ChessGame.Root` component accepts the following props:
-
-| Name        | Type       | Default | Description                                     |
-| ----------- | ---------- | ------- | ----------------------------------------------- |
-| children    | React.FC   |         | The children of the `ChessGame.Root` component. |
-| fen         | string     |         | The initial FEN of the chess game.              |
-| orientation | "w" \| "b" | "w"     | The orientation of the chess game.              |
-
-### ChessGame.Board
-
-The `ChessGame.Board` component is the main component of the `react-chess-game` package. It is used to render the chess board and the pieces. It uses the `ChessGameContext` to get the `Chess` instance and the `orientation` of the game.
-
-This version targets `react-chessboard` v5 and exposes a single `options` prop instead of spreading all board props.
-
-#### Props
-
-Accepts a single prop:
-
-| Name     | Type                | Description                                                                                        |
-| -------- | ------------------- | -------------------------------------------------------------------------------------------------- |
-| options? | `ChessboardOptions` | Forwarded to `react-chessboard` v5 `Chessboard({ options })`. Your values merge with the defaults. |
-
-Quick example (custom styles and event handlers):
-
-```tsx
-<ChessGame.Root>
-  <ChessGame.Board
-    options={{
-      squareStyles: { e4: { boxShadow: "inset 0 0 0 2px #4f46e5" } },
-      onPieceDrop: ({ sourceSquare, targetSquare }) => {
-        // return boolean to accept/reject drop
-        return true;
-      },
-      showNotation: true,
-      animationDurationInMs: 300,
-    }}
-  />
-
-  {/* Other parts like <ChessGame.Sounds /> or <ChessGame.KeyboardControls /> */}
-</ChessGame.Root>
-```
-
-### ChessGame.Sounds
-
-The `ChessGame.Sounds` component is used to provide the sounds for the chess game. By default, it uses built-in sounds, but you can provide your own sounds. Sounds must be provided as base 64 encoded strings.
-
-#### Props
-
-The `ChessGame.Sounds` component accepts the following props:
-
-| Name     | Type   | Default | Description                                       |
-| -------- | ------ | ------- | ------------------------------------------------- |
-| check    | string |         | The sound to play when a player is in check.      |
-| move     | string |         | The sound to play when a player makes a move.     |
-| capture  | string |         | The sound to play when a player captures a piece. |
-| gameOver | string |         | The sound to play when the game is over.          |
-
-### ChessGame.KeyboardControls
-
-The `ChessGame.KeyboardControls` component is used to provide keyboard controls for navigating through the chess game. By default, it enables arrow key controls for moving through game history, but you can customize the key bindings.
-
-#### Props
-
-The `ChessGame.KeyboardControls` component accepts the following props:
-
-| Name     | Type             | Default                 | Description                                                                                                                                                              |
-| -------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| controls | KeyboardControls | defaultKeyboardControls | Object mapping key names to handler functions. The default controls are: ArrowLeft (previous move), ArrowRight (next move), ArrowUp (go to start), ArrowDown (go to end) |
-
-### useChessGameContext
-
-The `useChessGameContext` hook is used to get the `ChessGameContext` from the `ChessGame.Root` component. It can be used to customize the chess game.
-
-#### Returns
-
-The `useChessGameContext` hook returns the following values:
-
-| Name             | Type       | Description                                                                            |
-| ---------------- | ---------- | -------------------------------------------------------------------------------------- |
-| game             | Chess      | The underlying `Chess.js` instance.                                                    |
-| orientation      | "w" \| "b" | The orientation of the chess game.                                                     |
-| currentFen       | string     | The current FEN string representing the board position.                                |
-| currentPosition  | string     | The current move in the game history.                                                  |
-| currentMoveIndex | number     | The index of the current move in the game history.                                     |
-| isLatestMove     | boolean    | Whether the current position is the latest move in the game.                           |
-| methods          | Methods    | The methods you can use to interact with the chess game.                               |
-| info             | Info       | The info of the chess game, calculated using the chess instance using chess.js methods |
-
-#### Methods
-
-The `useChessGameContext` hook also exposes these methods:
-
-| Name             | Type                            | Description                                                     |
-| ---------------- | ------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- | --- | ------------------ | ------------------------------------------------------------------ |
-| makeMove         | `(move: string                  | { from: Square; to: Square; promotion?: "q"                     | "r"                                                                  | "b" | "n" }) => boolean` | Attempts a move at the latest position; returns `true` if applied. |
-| setPosition      | `(fen: string, orientation: "w" | "b") => void`                                                   | Sets a new FEN and orientation, resets history navigation to latest. |
-| flipBoard        | `() => void`                    | Flips the board orientation.                                    |
-| goToMove         | `(moveIndex: number) => void`   | Jumps to a specific move index (`-1` is the starting position). |
-| goToStart        | `() => void`                    | Goes to the starting position.                                  |
-| goToEnd          | `() => void`                    | Goes to the latest move.                                        |
-| goToPreviousMove | `() => void`                    | Goes to the previous move.                                      |
-| goToNextMove     | `() => void`                    | Goes to the next move.                                          |
-
-#### Info
-
-The `useChessGameContext` hook returns the following info:
-
-| Name                   | Type       | Description                                                                |
-| ---------------------- | ---------- | -------------------------------------------------------------------------- |
-| turn                   | "w" \| "b" | The turn of the chess game                                                 |
-| isPlayerTurn           | boolean    | Whether it is the player's turn                                            |
-| isOpponentTurn         | boolean    | Whether it is the opponent's turn                                          |
-| moveNumber             | number     | The number of the current move                                             |
-| lastMove               | Move       | The last move made in the chess game                                       |
-| isCheck                | boolean    | Whether the player is in check                                             |
-| isCheckmate            | boolean    | Whether the player is in checkmate                                         |
-| isDraw                 | boolean    | Whether the game is a draw                                                 |
-| isStalemate            | boolean    | Whether the game is a stalemate                                            |
-| isThreefoldRepetition  | boolean    | Whether the game is a threefold repetition                                 |
-| isInsufficientMaterial | boolean    | Whether the game is a insufficient material                                |
-| isGameOver             | boolean    | Whether the game is over                                                   |
-| isDrawn                | boolean    | Whether the game is drawn                                                  |
-| hasPlayerWon           | boolean    | Whether the player (the side specified in the `orientation` prop) has won  |
-| hasPlayerLost          | boolean    | Whether the player (the side specified in the `orientation` prop) has lost |
-
-## 📝 License
-
-This project is [MIT](https://opensource.org/licenses/MIT) licensed.
-
-## Show your support
-
-Give a ⭐️ if this project helped you!

package/coverage/clover.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<coverage generated="1746218683707" clover="3.2.0">
-  <project timestamp="1746218683707" name="All files">
-    <metrics statements="0" coveredstatements="0" conditionals="0" coveredconditionals="0" methods="0" coveredmethods="0" elements="0" coveredelements="0" complexity="0" loc="0" ncloc="0" packages="0" files="0" classes="0"/>
-  </project>
-</coverage>

package/coverage/coverage-final.json

@@ -1 +0,0 @@
-{}