@react-chess-tools/react-chess-game 1.0.0 → 1.0.2

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

@@ -5,21 +5,33 @@ import { ChessGameContext } from "../../../hooks/useChessGameContext";
 import { ThemeProvider } from "../../../theme/context";
 import { mergeTheme } from "../../../theme/utils";
 import type { PartialChessGameTheme } from "../../../theme/types";
+import type { TimeControlConfig } from "@react-chess-tools/react-chess-clock";
 
 export interface RootProps {
   fen?: string;
   orientation?: Color;
   /** Optional theme configuration. Supports partial themes - only override the colors you need. */
   theme?: PartialChessGameTheme;
+  /** Optional clock configuration to enable chess clock functionality */
+  timeControl?: TimeControlConfig;
+  /** Auto-switch clock on move (default: true) */
+  autoSwitchOnMove?: boolean;
 }
 
 export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
   fen,
   orientation,
   theme,
+  timeControl,
+  autoSwitchOnMove,
   children,
 }) => {
-  const context = useChessGame({ fen, orientation });
+  const context = useChessGame({
+    fen,
+    orientation,
+    timeControl,
+    autoSwitchOnMove,
+  });
 
   // Merge partial theme with defaults
   const mergedTheme = React.useMemo(() => mergeTheme(theme), [theme]);
@@ -30,3 +42,5 @@ export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
     </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();
+  });
+});

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

@@ -0,0 +1,50 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessGame } from "../..";
+import { Root } from "../Root";
+
+describe("ChessGame.Root", () => {
+  it("should have correct displayName", () => {
+    expect(Root.displayName).toBe("ChessGame.Root");
+  });
+
+  it("should render children correctly", () => {
+    render(
+      <ChessGame.Root>
+        <div data-testid="child">Child Component</div>
+      </ChessGame.Root>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(screen.getByText("Child Component")).toBeInTheDocument();
+  });
+
+  it("should render multiple children", () => {
+    render(
+      <ChessGame.Root>
+        <div data-testid="child-1">Child 1</div>
+        <div data-testid="child-2">Child 2</div>
+        <div data-testid="child-3">Child 3</div>
+      </ChessGame.Root>,
+    );
+
+    expect(screen.getByTestId("child-1")).toBeInTheDocument();
+    expect(screen.getByTestId("child-2")).toBeInTheDocument();
+    expect(screen.getByTestId("child-3")).toBeInTheDocument();
+  });
+
+  it("should NOT render a DOM element wrapper", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <div data-testid="child">Child</div>
+      </ChessGame.Root>,
+    );
+
+    // The child should be in the container
+    const child = screen.getByTestId("child");
+    expect(child).toBeInTheDocument();
+    // Root itself doesn't add any DOM elements - it's just a fragment/context provider
+    expect(container.innerHTML).toContain('data-testid="child"');
+  });
+});

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

@@ -0,0 +1,22 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessGame } from "../..";
+import { Sounds } from "../Sounds";
+
+describe("ChessGame.Sounds", () => {
+  it("should have correct displayName", () => {
+    expect(Sounds.displayName).toBe("ChessGame.Sounds");
+  });
+
+  it("should render null (no DOM element)", () => {
+    const { container } = render(
+      <ChessGame.Root>
+        <ChessGame.Sounds />
+      </ChessGame.Root>,
+    );
+
+    // Sounds should not render any DOM elements
+    expect(container.querySelector("*")).toBeNull();
+  });
+});

package/src/hooks/useChessGame.ts

@@ -1,22 +1,31 @@
-import React, { useEffect } from "react";
+import React, { useEffect, useRef } from "react";
 import { Chess, Color } from "chess.js";
 import { cloneGame, getCurrentFen, getGameInfo } from "../utils/chess";
+import { useOptionalChessClock } from "@react-chess-tools/react-chess-clock";
+import type { TimeControlConfig } from "@react-chess-tools/react-chess-clock";
 
 export type useChessGameProps = {
   fen?: string;
   orientation?: Color;
+  /** Optional clock configuration to enable chess clock functionality */
+  timeControl?: TimeControlConfig;
+  /** Automatically switch the clock after each move (default: true).
+   * Set to false to let players manually press the clock, mimicking real-life over-the-board play. */
+  autoSwitchOnMove?: boolean;
 };
 
 export const useChessGame = ({
   fen,
   orientation: initialOrientation,
+  timeControl,
+  autoSwitchOnMove = true,
 }: useChessGameProps = {}) => {
   const [game, setGame] = React.useState(() => {
     try {
       return new Chess(fen);
     } catch (e) {
       console.error("Invalid FEN:", fen, e);
-      return new Chess(); // Return empty board
+      return new Chess();
     }
   });
 
@@ -35,10 +44,8 @@ export const useChessGame = ({
   const [currentMoveIndex, setCurrentMoveIndex] = React.useState(-1);
 
   const history = React.useMemo(() => game.history(), [game]);
-  const isLatestMove = React.useMemo(
-    () => currentMoveIndex === history.length - 1 || currentMoveIndex === -1,
-    [currentMoveIndex, history.length],
-  );
+  const isLatestMove =
+    currentMoveIndex === history.length - 1 || currentMoveIndex === -1;
 
   const info = React.useMemo(
     () => getGameInfo(game, orientation),
@@ -47,13 +54,18 @@ export const useChessGame = ({
 
   const currentFen = React.useMemo(
     () => getCurrentFen(fen, game, currentMoveIndex),
-    [game, currentMoveIndex],
+    [fen, game, currentMoveIndex],
   );
 
-  const currentPosition = React.useMemo(
-    () => game.history()[currentMoveIndex],
-    [game, currentMoveIndex],
-  );
+  const currentPosition = game.history()[currentMoveIndex];
+
+  const clockState = useOptionalChessClock(timeControl);
+
+  // Keep clockState in a ref to avoid re-creating makeMove on every clock tick.
+  // The clock state object is recreated on every render (especially during active
+  // ticking), which would defeat the useCallback memoization.
+  const clockStateRef = useRef(clockState);
+  clockStateRef.current = clockState;
 
   const setPosition = React.useCallback((fen: string, orientation: Color) => {
     try {
@@ -74,17 +86,42 @@ export const useChessGame = ({
         return false;
       }
 
+      // Access clock state via ref to avoid stale closures while keeping
+      // the callback stable (not re-created on every clock tick)
+      const clock = clockStateRef.current;
+
+      // Don't allow moves after clock timeout
+      if (clock && clock.timeout !== null) {
+        return false;
+      }
+
       try {
         const copy = cloneGame(game);
         copy.move(move);
         setGame(copy);
         setCurrentMoveIndex(copy.history().length - 1);
+
+        // Auto-start clock on first move
+        if (clock && clock.status === "idle") {
+          clock.methods.start();
+        }
+
+        // Pause clock on game over (checked immediately after move)
+        if (clock && clock.status === "running" && copy.isGameOver()) {
+          clock.methods.pause();
+        }
+
+        // Auto-switch clock after a move is made if enabled
+        if (autoSwitchOnMove && clock && clock.status !== "finished") {
+          clock.methods.switch();
+        }
+
         return true;
       } catch (e) {
         return false;
       }
     },
-    [isLatestMove, game],
+    [isLatestMove, game, autoSwitchOnMove],
   );
 
   const flipBoard = React.useCallback(() => {
@@ -145,5 +182,6 @@ export const useChessGame = ({
     isLatestMove,
     info,
     methods,
+    clock: clockState,
   };
 };

package/src/index.ts

@@ -1,6 +1,16 @@
 // Components
 export { ChessGame } from "./components/ChessGame";
 
+// Clock - Re-export from react-chess-clock for convenience
+export { ChessClock } from "@react-chess-tools/react-chess-clock";
+export type {
+  TimeControlConfig,
+  TimeControlInput,
+  TimingMethod,
+  ClockStartMode,
+  UseChessClockReturn,
+} from "@react-chess-tools/react-chess-clock";
+
 // Hooks & Context
 export { useChessGameContext } from "./hooks/useChessGameContext";
 export { useChessGame } from "./hooks/useChessGame";

package/src/theme/__tests__/context.test.tsx

@@ -38,21 +38,6 @@ describe("useChessGameTheme", () => {
 });
 
 describe("ThemeProvider", () => {
-  it("should render children", () => {
-    const TestComponent = () => {
-      const theme = useChessGameTheme();
-      return <div data-testid="theme-check">{theme.state.lastMove}</div>;
-    };
-
-    const { result } = renderHook(() => useChessGameTheme(), {
-      wrapper: ({ children }) => (
-        <ThemeProvider theme={defaultGameTheme}>{children}</ThemeProvider>
-      ),
-    });
-
-    expect(result.current).toBeTruthy();
-  });
-
   it("should allow nested providers with inner provider winning", () => {
     const outerTheme = {
       ...defaultGameTheme,

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!