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

package/src/components/ChessGame/parts/Board.tsx

@@ -12,229 +12,240 @@ import {
 } from "../../../utils/board";
 import { isLegalMove, requiresPromotion } from "../../../utils/chess";
 import { useChessGameContext } from "../../../hooks/useChessGameContext";
+import { useChessGameTheme } from "../../../theme/context";
 
-export interface ChessGameProps {
+export interface ChessGameProps extends React.HTMLAttributes<HTMLDivElement> {
   options?: ChessboardOptions;
 }
 
-export const Board: React.FC<ChessGameProps> = ({ options = {} }) => {
-  const gameContext = useChessGameContext();
+export const Board = React.forwardRef<HTMLDivElement, ChessGameProps>(
+  ({ options = {}, className, style: userStyle, ...rest }, ref) => {
+    const gameContext = useChessGameContext();
+    const theme = useChessGameTheme();
 
-  if (!gameContext) {
-    throw new Error("ChessGameContext not found");
-  }
+    if (!gameContext) {
+      throw new Error("ChessGameContext not found");
+    }
 
-  const {
-    game,
-    currentFen,
-    orientation,
-    info,
-    isLatestMove,
-    methods: { makeMove },
-  } = gameContext;
+    const {
+      game,
+      currentFen,
+      orientation,
+      info,
+      isLatestMove,
+      methods: { makeMove },
+    } = gameContext;
 
-  const { turn, isGameOver } = info;
+    const { turn, isGameOver } = info;
 
-  const [activeSquare, setActiveSquare] = React.useState<Square | null>(null);
+    const [activeSquare, setActiveSquare] = React.useState<Square | null>(null);
 
-  const [promotionMove, setPromotionMove] =
-    React.useState<Partial<Move> | null>(null);
+    const [promotionMove, setPromotionMove] =
+      React.useState<Partial<Move> | null>(null);
 
-  const onSquareClick = (square: Square) => {
-    if (isGameOver) {
-      return;
-    }
+    const onSquareClick = (square: Square) => {
+      if (isGameOver) {
+        return;
+      }
 
-    if (activeSquare === null) {
-      const squadreInfo = game.get(square);
-      if (squadreInfo && squadreInfo.color === turn) {
-        return setActiveSquare(square);
+      if (activeSquare === null) {
+        const squadreInfo = game.get(square);
+        if (squadreInfo && squadreInfo.color === turn) {
+          return setActiveSquare(square);
+        }
+        return;
       }
-      return;
-    }
 
-    if (
-      !isLegalMove(game, {
-        from: activeSquare,
-        to: square,
-        promotion: "q",
-      })
-    ) {
-      return setActiveSquare(null);
-    }
+      if (
+        !isLegalMove(game, {
+          from: activeSquare,
+          to: square,
+          promotion: "q",
+        })
+      ) {
+        return setActiveSquare(null);
+      }
 
-    if (
-      requiresPromotion(game, {
-        from: activeSquare,
-        to: square,
-        promotion: "q",
-      })
-    ) {
-      return setPromotionMove({
+      if (
+        requiresPromotion(game, {
+          from: activeSquare,
+          to: square,
+          promotion: "q",
+        })
+      ) {
+        return setPromotionMove({
+          from: activeSquare,
+          to: square,
+        });
+      }
+
+      setActiveSquare(null);
+      makeMove({
         from: activeSquare,
         to: square,
       });
-    }
-
-    setActiveSquare(null);
-    makeMove({
-      from: activeSquare,
-      to: square,
-    });
-  };
+    };
+
+    const onPromotionPieceSelect = (piece: string): void => {
+      if (promotionMove?.from && promotionMove?.to) {
+        makeMove({
+          from: promotionMove.from,
+          to: promotionMove.to,
+          promotion: piece.toLowerCase(),
+        });
+        setPromotionMove(null);
+      }
+    };
 
-  const onPromotionPieceSelect = (piece: string): void => {
-    if (promotionMove?.from && promotionMove?.to) {
-      makeMove({
-        from: promotionMove.from,
-        to: promotionMove.to,
-        promotion: piece.toLowerCase(),
-      });
+    const onSquareRightClick = () => {
+      setActiveSquare(null);
       setPromotionMove(null);
-    }
-  };
-
-  const onSquareRightClick = () => {
-    setActiveSquare(null);
-    setPromotionMove(null);
-  };
-
-  // Calculate square width for precise positioning
-  const squareWidth = React.useMemo(() => {
-    if (typeof document === "undefined") return 80;
-    const squareElement = document.querySelector(`[data-square]`);
-    return squareElement?.getBoundingClientRect()?.width ?? 80;
-  }, [promotionMove]);
-
-  // Calculate promotion square position
-  const promotionSquareLeft = React.useMemo(() => {
-    if (!promotionMove?.to) return 0;
-    const column = promotionMove.to.match(/^[a-h]/)?.[0] ?? "a";
+    };
+
+    // Calculate square width for precise positioning
+    const squareWidth = React.useMemo(() => {
+      if (typeof document === "undefined") return 80;
+      const squareElement = document.querySelector(`[data-square]`);
+      return squareElement?.getBoundingClientRect()?.width ?? 80;
+    }, [promotionMove]);
+
+    // Calculate promotion square position
+    const promotionSquareLeft = React.useMemo(() => {
+      if (!promotionMove?.to) return 0;
+      const column = promotionMove.to.match(/^[a-h]/)?.[0] ?? "a";
+      return (
+        squareWidth *
+        chessColumnToColumnIndex(
+          column,
+          8,
+          orientation === "b" ? "black" : "white",
+        )
+      );
+    }, [promotionMove, squareWidth, orientation]);
+
+    const baseOptions: ChessboardOptions = {
+      squareStyles: getCustomSquareStyles(game, info, activeSquare, theme),
+      boardOrientation: orientation === "b" ? "black" : "white",
+      position: currentFen,
+      showNotation: true,
+      showAnimations: isLatestMove,
+      lightSquareStyle: theme.board.lightSquare,
+      darkSquareStyle: theme.board.darkSquare,
+      canDragPiece: ({ piece }) => {
+        if (isGameOver) return false;
+        return piece.pieceType[0] === turn;
+      },
+      dropSquareStyle: theme.state.dropSquare,
+      onPieceDrag: ({ piece, square }) => {
+        if (piece.pieceType[0] === turn) {
+          setActiveSquare(square as Square);
+        }
+      },
+      onPieceDrop: ({ sourceSquare, targetSquare }) => {
+        setActiveSquare(null);
+        const moveData = {
+          from: sourceSquare as Square,
+          to: targetSquare as Square,
+        };
+
+        // Check if promotion is needed
+        if (requiresPromotion(game, { ...moveData, promotion: "q" })) {
+          setPromotionMove(moveData);
+          return false; // Prevent the move until promotion is selected
+        }
+
+        return makeMove(moveData);
+      },
+      onSquareClick: ({ square }) => {
+        if (square.match(/^[a-h][1-8]$/)) {
+          onSquareClick(square as Square);
+        }
+      },
+      onSquareRightClick: onSquareRightClick,
+      allowDrawingArrows: true,
+      animationDurationInMs: game.history().length === 0 ? 0 : 300,
+    };
+
+    const mergedOptions = deepMergeChessboardOptions(baseOptions, options);
+
+    const mergedStyle = {
+      ...userStyle,
+      position: "relative" as const,
+    };
+
     return (
-      squareWidth *
-      chessColumnToColumnIndex(
-        column,
-        8,
-        orientation === "b" ? "black" : "white",
-      )
+      <div ref={ref} className={className} style={mergedStyle} {...rest}>
+        <Chessboard options={mergedOptions} />
+        {promotionMove && (
+          <>
+            {/* Backdrop overlay - click to cancel */}
+            <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: 1000,
+              }}
+            />
+            {/* Promotion piece selection */}
+            <div
+              style={{
+                position: "absolute",
+                top: promotionMove.to?.[1]?.includes("8") ? 0 : "auto",
+                bottom: promotionMove.to?.[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) => (
+                <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()}` as keyof typeof defaultPieces
+                  ]()}
+                </button>
+              ))}
+            </div>
+          </>
+        )}
+      </div>
     );
-  }, [promotionMove, squareWidth, orientation]);
-
-  const baseOptions: ChessboardOptions = {
-    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 as Square);
-      }
-    },
-    onPieceDrop: ({ sourceSquare, targetSquare }) => {
-      setActiveSquare(null);
-      const moveData = {
-        from: sourceSquare as Square,
-        to: targetSquare as Square,
-      };
-
-      // Check if promotion is needed
-      if (requiresPromotion(game, { ...moveData, promotion: "q" })) {
-        setPromotionMove(moveData);
-        return false; // Prevent the move until promotion is selected
-      }
+  },
+);
 
-      return makeMove(moveData);
-    },
-    onSquareClick: ({ square }) => {
-      if (square.match(/^[a-h][1-8]$/)) {
-        onSquareClick(square as Square);
-      }
-    },
-    onSquareRightClick: onSquareRightClick,
-    allowDrawingArrows: true,
-    animationDurationInMs: game.history().length === 0 ? 0 : 300,
-  };
-
-  const mergedOptions = deepMergeChessboardOptions(baseOptions, options);
-
-  return (
-    <div style={{ position: "relative" }}>
-      <Chessboard options={mergedOptions} />
-      {promotionMove && (
-        <>
-          {/* Backdrop overlay - click to cancel */}
-          <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: 1000,
-            }}
-          />
-          {/* Promotion piece selection */}
-          <div
-            style={{
-              position: "absolute",
-              top: promotionMove.to?.[1]?.includes("8") ? 0 : "auto",
-              bottom: promotionMove.to?.[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) => (
-              <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()}` as keyof typeof defaultPieces
-                ]()}
-              </button>
-            ))}
-          </div>
-        </>
-      )}
-    </div>
-  );
-};
+Board.displayName = "ChessGame.Board";

package/src/components/ChessGame/parts/KeyboardControls.tsx

@@ -16,6 +16,13 @@ export const defaultKeyboardControls: KeyboardControls = {
   ArrowDown: (context) => context.methods.goToEnd(),
 };
 
+/**
+ * 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;
 };
@@ -31,3 +38,5 @@ export const KeyboardControls: React.FC<KeyboardControlsProps> = ({
   useKeyboardControls(keyboardControls);
   return null;
 };
+
+KeyboardControls.displayName = "ChessGame.KeyboardControls";

package/src/components/ChessGame/parts/Root.tsx

@@ -2,21 +2,33 @@ import React from "react";
 import { Color } from "chess.js";
 import { useChessGame } from "../../../hooks/useChessGame";
 import { ChessGameContext } from "../../../hooks/useChessGameContext";
+import { ThemeProvider } from "../../../theme/context";
+import { mergeTheme } from "../../../theme/utils";
+import type { PartialChessGameTheme } from "../../../theme/types";
 
 export interface RootProps {
   fen?: string;
   orientation?: Color;
+  /** Optional theme configuration. Supports partial themes - only override the colors you need. */
+  theme?: PartialChessGameTheme;
 }
 
 export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
   fen,
   orientation,
+  theme,
   children,
 }) => {
   const context = useChessGame({ fen, orientation });
+
+  // Merge partial theme with defaults
+  const mergedTheme = React.useMemo(() => mergeTheme(theme), [theme]);
+
   return (
     <ChessGameContext.Provider value={context}>
-      {children}
+      <ThemeProvider theme={mergedTheme}>{children}</ThemeProvider>
     </ChessGameContext.Provider>
   );
 };
+
+Root.displayName = "ChessGame.Root";

package/src/components/ChessGame/parts/Sounds.tsx

@@ -2,6 +2,13 @@ import { useMemo } from "react";
 import { defaultSounds, type Sound } from "../../../assets/sounds";
 import { useBoardSounds } from "../../../hooks/useBoardSounds";
 
+/**
+ * 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.
+ */
 export type SoundsProps = {
   sounds?: Partial<Record<Sound, string>>;
 };
@@ -23,3 +30,5 @@ export const Sounds: React.FC<SoundsProps> = ({ sounds }) => {
   useBoardSounds(customSoundsAudios);
   return null;
 };
+
+Sounds.displayName = "ChessGame.Sounds";

package/src/components/ChessGame/parts/__tests__/Board.test.tsx

@@ -0,0 +1,122 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessGame } from "../..";
+import { Board } from "../Board";
+
+describe("ChessGame.Board", () => {
+  it("should have correct displayName", () => {
+    expect(Board.displayName).toBe("ChessGame.Board");
+  });
+
+  it("should forward ref to div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+
+    render(
+      <ChessGame.Root>
+        <Board ref={ref} />
+      </ChessGame.Root>,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it("should apply custom className", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <Board className="custom-board-class" />
+      </ChessGame.Root>,
+    );
+
+    const board = container.querySelector(".custom-board-class");
+    expect(board).toBeInTheDocument();
+  });
+
+  it("should merge multiple className props", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <Board className="class-1 class-2" />
+      </ChessGame.Root>,
+    );
+
+    const board = container.querySelector(".class-1");
+    expect(board).toHaveClass("class-1");
+    expect(board).toHaveClass("class-2");
+  });
+
+  it("should apply custom style", () => {
+    const customStyle = { border: "2px solid red", margin: "10px" };
+
+    const { container } = render(
+      <ChessGame.Root>
+        <Board style={customStyle} />
+      </ChessGame.Root>,
+    );
+
+    const board = container.firstElementChild as HTMLElement;
+    expect(board).toHaveStyle({ border: "2px solid red" });
+    expect(board).toHaveStyle({ margin: "10px" });
+  });
+
+  it("should apply custom id", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <Board id="custom-board-id" />
+      </ChessGame.Root>,
+    );
+
+    const board = container.querySelector("#custom-board-id");
+    expect(board).toBeInTheDocument();
+  });
+
+  it("should apply data-* attributes", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <Board data-testid="board" data-custom="value" />
+      </ChessGame.Root>,
+    );
+
+    const board = container.querySelector("[data-custom='value']");
+    expect(board).toHaveAttribute("data-testid", "board");
+  });
+
+  it("should apply aria-* attributes", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <Board aria-label="Chess board" aria-describedby="board-desc" />
+      </ChessGame.Root>,
+    );
+
+    const board = container.firstElementChild as HTMLElement;
+    expect(board).toHaveAttribute("aria-label", "Chess board");
+    expect(board).toHaveAttribute("aria-describedby", "board-desc");
+  });
+
+  it("should accept custom onClick handler", () => {
+    const handleClick = jest.fn();
+
+    const { container } = render(
+      <ChessGame.Root>
+        <Board onClick={handleClick} />
+      </ChessGame.Root>,
+    );
+
+    const board = container.firstElementChild as HTMLElement;
+    board.click();
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("should throw error when used outside ChessGame.Root", () => {
+    // Suppress console.error for this test
+    const consoleError = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() => {
+      render(<Board />);
+    }).toThrow("useChessGameContext must be used within a ChessGame component");
+
+    consoleError.mockRestore();
+  });
+});

package/src/components/ChessGame/parts/__tests__/KeyboardControls.test.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessGame } from "../..";
+import { KeyboardControls } from "../KeyboardControls";
+
+describe("ChessGame.KeyboardControls", () => {
+  it("should have correct displayName", () => {
+    expect(KeyboardControls.displayName).toBe("ChessGame.KeyboardControls");
+  });
+
+  it("should render null (no DOM element)", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <ChessGame.KeyboardControls />
+      </ChessGame.Root>,
+    );
+
+    // KeyboardControls should not render any DOM elements
+    expect(container.querySelector("*")).toBeNull();
+  });
+
+  it("should throw error when used outside ChessGame.Root", () => {
+    const consoleError = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() => {
+      render(<ChessGame.KeyboardControls />);
+    }).toThrow();
+
+    consoleError.mockRestore();
+  });
+});