@react-chess-tools/react-chess-game 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @react-chess-tools/react-chess-game
 
+## 0.5.1
+
+### Patch Changes
+
+- f50ac0f: feat: improve chessboard options merging with deep merge utility
+
+## 0.5.0
+
+### Minor Changes
+
+- f58c1ac: chore: upgrade to react-chessboard v5
+
+### Patch Changes
+
+- 95cf0c3: docs: update README documentation for react-chess-tools packages
+- a877019: fix: handle sound playback errors gracefully
+
 ## 0.4.2
 
 ### Patch Changes

package/README.MD

@@ -18,7 +18,7 @@ This project is a React-based chess game that allows users to play chess online.
 - Square highlighting
 - Keyboard controls
 
-It is build 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 ehance the component game. Is also provides a set of default components that you can use to build your next chess app.
+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
 
@@ -39,11 +39,11 @@ To use the `react-chess-game` package, you can import the `ChessGame` component
 ```tsx
 import { ChessGame } from "@react-chess-tools/react-chess-game";
 
-const App = () => {
+const App = () => (
   <ChessGame.Root>
     <ChessGame.Board />
-  </ChessGame.Root>;
-};
+  </ChessGame.Root>
+);
 ```
 
 ## Documentation
@@ -58,23 +58,49 @@ The `ChessGame.Root` component is the root component of the `react-chess-game` p
 
 The `ChessGame.Root` component accepts the following props:
 
-| Name        | Type       | Default          | Description                                     |
-| ----------- | ---------- | ---------------- | ----------------------------------------------- |
-| children    | React.FC   |                  | The children of the `ChessGame.Root` component. |
-| fen         | string     | initial position | The FEN of the chess game.                      |
-| orientation | "w" \| "b" | "white"          | The orientation of the chess game.              |
+| 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
 
-All the props from Chessboard.js are supported. You can find the full list of props [here](https://github.com/Clariity/react-chessboard#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 the sounds from the `react-chess-sounds` package, but you can provide your own sounds. Sounds must be provided as base 64 encoded strings.
+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
 
@@ -107,27 +133,31 @@ The `useChessGameContext` hook is used to get the `ChessGameContext` from the `C
 
 The `useChessGameContext` hook returns the following values:
 
-| Name        | Type       | Description                                                                            |
-| ----------- | ---------- | -------------------------------------------------------------------------------------- |
-| chess       | Chess      | The `Chess` instance of the chess game.                                                |
-| orientation | "w" \| "b" | The orientation of the chess 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 |
+| 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 `useChessGameContextContext` hook returns the following methods:
+The `useChessGameContext` hook also exposes these methods:
 
-| Name             | Type                        | Description                                  |
-| ---------------- | --------------------------- | -------------------------------------------- |
-| makeMove         | (move: string) => void      | Makes a move in the chess game.              |
-| setPostion       | (fen: string) => void       | Sets the position of the chess game.         |
-| flipBoard        | () => void                  | Flips the board.                             |
-| goToMove         | (moveIndex: number) => void | Goes to a specific move in the game history. |
-| goToStart        | () => void                  | Goes to the starting position.               |
-| goToEnd          | () => void                  | Goes to the latest position.                 |
-| goToPreviousMove | () => void                  | Goes to the previous move.                   |
-| goToNextMove     | () => void                  | Goes to the next move.                       |
+| 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
 
@@ -150,11 +180,6 @@ The `useChessGameContext` hook returns the following info:
 | 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 |
-| 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                |
-| game                   | Chess      | The underlying Chess.js instance                                           |
 
 ## 📝 License
 

package/dist/index.d.mts

@@ -1,6 +1,5 @@
-import * as React$1 from 'react';
-import React__default from 'react';
-import { Chessboard } from 'react-chessboard';
+import { ChessboardOptions } from 'react-chessboard';
+import * as react from 'react';
 import * as chess_js from 'chess.js';
 import { Color, Chess } from 'chess.js';
 
@@ -11,7 +10,8 @@ type SoundsProps = {
     sounds?: Partial<Record<Sound, string>>;
 };
 
-interface ChessGameProps extends React__default.ComponentProps<typeof Chessboard> {
+interface ChessGameProps {
+    options?: ChessboardOptions;
 }
 
 interface RootProps {
@@ -88,7 +88,7 @@ declare const useChessGameContext: () => {
             from: string;
             to: string;
             promotion?: string | undefined;
-        }) => boolean;
+        } | null) => boolean;
         setPosition: (fen: string, orientation: chess_js.Color) => void;
         flipBoard: () => void;
         goToMove: (moveIndex: number) => void;
@@ -107,10 +107,10 @@ 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.FC<ChessGameProps>;
-    Sounds: React$1.FC<SoundsProps>;
-    KeyboardControls: React$1.FC<{
+    Root: react.FC<react.PropsWithChildren<RootProps>>;
+    Board: react.FC<ChessGameProps>;
+    Sounds: react.FC<SoundsProps>;
+    KeyboardControls: react.FC<{
         controls?: KeyboardControls | undefined;
     }>;
 };

package/dist/index.mjs

@@ -224,9 +224,14 @@ var Root = ({
 
 // src/components/ChessGame/parts/Board.tsx
 import React4 from "react";
-import { Chessboard } from "react-chessboard";
+import {
+  Chessboard,
+  defaultPieces,
+  chessColumnToColumnIndex
+} from "react-chessboard";
 
 // src/utils/board.ts
+import { merge } from "lodash";
 var LAST_MOVE_COLOR = "rgba(255, 255, 0, 0.5)";
 var CHECK_COLOR = "rgba(255, 0, 0, 0.5)";
 var getCustomSquareStyles = (game, info, activeSquare) => {
@@ -267,12 +272,28 @@ var getCustomSquareStyles = (game, info, activeSquare) => {
   }
   return customSquareStyles;
 };
+var deepMergeChessboardOptions = (baseOptions, customOptions) => {
+  if (!customOptions) {
+    return { ...baseOptions };
+  }
+  const result = merge({}, baseOptions, customOptions, {
+    customizer: (_objValue, srcValue) => {
+      if (typeof srcValue === "function") {
+        return srcValue;
+      }
+      if (Array.isArray(srcValue)) {
+        return srcValue;
+      }
+      return void 0;
+    }
+  });
+  delete result.customizer;
+  return result;
+};
 
 // src/components/ChessGame/parts/Board.tsx
-var Board = ({
-  customSquareStyles,
-  ...rest
-}) => {
+var Board = ({ options = {} }) => {
+  var _a, _b, _c;
   const gameContext = useChessGameContext();
   if (!gameContext) {
     throw new Error("ChessGameContext not found");
@@ -282,6 +303,7 @@ var Board = ({
     currentFen,
     orientation,
     info,
+    isLatestMove,
     methods: { makeMove }
   } = gameContext;
   const { turn, isGameOver } = info;
@@ -322,45 +344,138 @@ var Board = ({
     });
   };
   const onPromotionPieceSelect = (piece) => {
-    var _a;
-    if ((promotionMove == null ? void 0 : promotionMove.from) && (promotionMove == null ? void 0 : promotionMove.to) && piece) {
-      setPromotionMove(null);
-      return makeMove({
+    if ((promotionMove == null ? void 0 : promotionMove.from) && (promotionMove == null ? void 0 : promotionMove.to)) {
+      makeMove({
         from: promotionMove.from,
         to: promotionMove.to,
-        promotion: ((_a = piece == null ? void 0 : piece[1]) == null ? void 0 : _a.toLowerCase()) || "q"
+        promotion: piece.toLowerCase()
       });
+      setPromotionMove(null);
     }
-    return true;
   };
-  return /* @__PURE__ */ React4.createElement(
-    Chessboard,
-    {
-      customSquareStyles: {
-        ...getCustomSquareStyles(game, info, activeSquare),
-        ...customSquareStyles
-      },
-      boardOrientation: orientation === "b" ? "black" : "white",
-      position: currentFen,
-      showPromotionDialog: !!promotionMove,
-      onPromotionPieceSelect: promotionMove ? onPromotionPieceSelect : void 0,
-      onPieceDragBegin: (_2, square) => {
+  const onSquareRightClick = () => {
+    setActiveSquare(null);
+    setPromotionMove(null);
+  };
+  const squareWidth = React4.useMemo(() => {
+    var _a2;
+    if (typeof document === "undefined") return 80;
+    const squareElement = document.querySelector(`[data-square]`);
+    return ((_a2 = squareElement == null ? void 0 : squareElement.getBoundingClientRect()) == null ? void 0 : _a2.width) ?? 80;
+  }, [promotionMove]);
+  const promotionSquareLeft = React4.useMemo(() => {
+    var _a2;
+    if (!(promotionMove == null ? void 0 : promotionMove.to)) return 0;
+    const column = ((_a2 = promotionMove.to.match(/^[a-h]/)) == null ? void 0 : _a2[0]) ?? "a";
+    return squareWidth * chessColumnToColumnIndex(
+      column,
+      8,
+      orientation === "b" ? "black" : "white"
+    );
+  }, [promotionMove, squareWidth, orientation]);
+  const baseOptions = {
+    squareStyles: getCustomSquareStyles(game, info, activeSquare),
+    boardOrientation: orientation === "b" ? "black" : "white",
+    position: currentFen,
+    showNotation: true,
+    showAnimations: isLatestMove,
+    canDragPiece: ({ piece }) => {
+      if (isGameOver) return false;
+      return piece.pieceType[0] === turn;
+    },
+    dropSquareStyle: {
+      backgroundColor: "rgba(255, 255, 0, 0.4)"
+    },
+    onPieceDrag: ({ piece, square }) => {
+      if (piece.pieceType[0] === turn) {
         setActiveSquare(square);
-      },
-      onPieceDragEnd: () => {
-        setActiveSquare(null);
-      },
-      onPieceDrop: (sourceSquare, targetSquare, piece) => makeMove({
+      }
+    },
+    onPieceDrop: ({ sourceSquare, targetSquare }) => {
+      setActiveSquare(null);
+      const moveData = {
         from: sourceSquare,
-        to: targetSquare,
-        promotion: (piece == null ? void 0 : piece[1].toLowerCase()) || "q"
-      }),
-      onSquareClick,
-      areArrowsAllowed: true,
-      animationDuration: game.history().length === 0 ? 0 : 300,
-      ...rest
+        to: targetSquare
+      };
+      if (requiresPromotion(game, { ...moveData, promotion: "q" })) {
+        setPromotionMove(moveData);
+        return false;
+      }
+      return makeMove(moveData);
+    },
+    onSquareClick: ({ square }) => {
+      if (square.match(/^[a-h][1-8]$/)) {
+        onSquareClick(square);
+      }
+    },
+    onSquareRightClick,
+    allowDrawingArrows: true,
+    animationDurationInMs: game.history().length === 0 ? 0 : 300
+  };
+  const mergedOptions = deepMergeChessboardOptions(baseOptions, options);
+  return /* @__PURE__ */ React4.createElement("div", { style: { position: "relative" } }, /* @__PURE__ */ React4.createElement(Chessboard, { options: mergedOptions }), promotionMove && /* @__PURE__ */ React4.createElement(React4.Fragment, null, /* @__PURE__ */ React4.createElement(
+    "div",
+    {
+      onClick: () => setPromotionMove(null),
+      onContextMenu: (e) => {
+        e.preventDefault();
+        setPromotionMove(null);
+      },
+      style: {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        backgroundColor: "rgba(0, 0, 0, 0.1)",
+        zIndex: 1e3
+      }
     }
-  );
+  ), /* @__PURE__ */ React4.createElement(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        top: ((_b = (_a = promotionMove.to) == null ? void 0 : _a[1]) == null ? void 0 : _b.includes("8")) ? 0 : "auto",
+        bottom: ((_c = promotionMove.to) == null ? void 0 : _c[1].includes("1")) ? 0 : "auto",
+        left: promotionSquareLeft,
+        backgroundColor: "white",
+        width: squareWidth,
+        zIndex: 1001,
+        display: "flex",
+        flexDirection: "column",
+        boxShadow: "0 0 10px 0 rgba(0, 0, 0, 0.5)"
+      }
+    },
+    ["q", "r", "n", "b"].map((piece) => /* @__PURE__ */ React4.createElement(
+      "button",
+      {
+        key: piece,
+        onClick: () => onPromotionPieceSelect(piece),
+        onContextMenu: (e) => {
+          e.preventDefault();
+        },
+        style: {
+          width: "100%",
+          aspectRatio: "1",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 0,
+          border: "none",
+          cursor: "pointer",
+          backgroundColor: "white"
+        },
+        onMouseEnter: (e) => {
+          e.currentTarget.style.backgroundColor = "#f0f0f0";
+        },
+        onMouseLeave: (e) => {
+          e.currentTarget.style.backgroundColor = "white";
+        }
+      },
+      defaultPieces[`${turn}${piece.toUpperCase()}`]()
+    ))
+  )));
 };
 
 // src/components/ChessGame/parts/Sounds.tsx
@@ -377,26 +492,31 @@ var defaultSounds = {
 
 // src/hooks/useBoardSounds.ts
 import { useEffect as useEffect2 } from "react";
+var playSound = async (audioElement) => {
+  try {
+    await audioElement.play();
+  } catch (error) {
+    console.warn("Failed to play sound:", error.message);
+  }
+};
 var useBoardSounds = (sounds) => {
   const {
     info: { lastMove, isCheckmate }
   } = useChessGameContext();
   useEffect2(() => {
-    var _a, _b, _c;
     if (Object.keys(sounds).length === 0) {
       return;
     }
-    if (isCheckmate) {
-      (_a = sounds.gameOver) == null ? void 0 : _a.play();
+    if (isCheckmate && sounds.gameOver) {
+      playSound(sounds.gameOver);
       return;
     }
-    if (lastMove == null ? void 0 : lastMove.captured) {
-      (_b = sounds.capture) == null ? void 0 : _b.play();
+    if ((lastMove == null ? void 0 : lastMove.captured) && sounds.capture) {
+      playSound(sounds.capture);
       return;
     }
-    if (lastMove) {
-      (_c = sounds.move) == null ? void 0 : _c.play();
-      return;
+    if (lastMove && sounds.move) {
+      playSound(sounds.move);
     }
   }, [lastMove]);
 };