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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @react-chess-tools/react-chess-game
 
+## 1.0.2
+
+### Patch Changes
+
+- 93e1029: feat: add chess clock
+- Updated dependencies [93e1029]
+  - @react-chess-tools/react-chess-clock@1.0.1
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,7 @@
   - [ChessGame.Board](#chessgameboard)
   - [ChessGame.Sounds](#chessgamesounds)
   - [ChessGame.KeyboardControls](#chessgamekeyboardcontrols)
+  - [ChessGame.Clock](#chessgameclock)
 - [Hooks](#hooks)
   - [useChessGameContext](#usechessgamecontext)
 - [Examples](#examples)
@@ -36,12 +37,15 @@
 
 Built using a compound component pattern (similar to [Radix UI](https://www.radix-ui.com/)), it provides a `ChessGameContext` that you can use to customize and enhance the game while maintaining sensible defaults.
 
+The package now includes integrated chess clock functionality powered by [`@react-chess-tools/react-chess-clock`](https://www.npmjs.com/package/@react-chess-tools/react-chess-clock).
+
 ## Features
 
 - **Move-by-click** - Click to select and move pieces
 - **Sound effects** - Built-in sounds for moves, captures, check, and game over
 - **Square highlighting** - Visual feedback for valid moves and last move
 - **Keyboard controls** - Navigate through game history with arrow keys
+- **Integrated Chess Clock** - Built-in clock support with multiple timing methods
 - **Full game state** - Access to check, checkmate, stalemate, draw detection
 - **TypeScript** - Full TypeScript support with comprehensive type definitions
 - **Customizable** - Override any default with your own implementation
@@ -76,6 +80,23 @@ function App() {
 }
 ```
 
+With a chess clock:
+
+```tsx
+import { ChessGame } from "@react-chess-tools/react-chess-game";
+
+function App() {
+  return (
+    <ChessGame.Root timeControl={{ time: "5+3" }}>
+      <ChessGame.Clock.Display color="white" />
+      <ChessGame.Board />
+      <ChessGame.Clock.Display color="black" />
+      <ChessGame.Clock.PlayPause />
+    </ChessGame.Root>
+  );
+}
+```
+
 ## Demo
 
 Visit the [live demo](https://react-chess-tools.vercel.app/) to see the component in action.
@@ -84,18 +105,20 @@ Visit the [live demo](https://react-chess-tools.vercel.app/) to see the componen
 
 ### ChessGame.Root
 
-The root component that provides `ChessGameContext` to all child components. It instantiates a `Chess` instance using the `fen` prop.
+The root component that provides `ChessGameContext` to all child components. It instantiates a `Chess` instance using the `fen` prop and optionally sets up a chess clock.
 
 **Note:** This is a logic-only component (Context Provider). It does not render any DOM elements.
 
 #### Props
 
-| Name          | Type                    | Default           | Description                                  |
-| ------------- | ----------------------- | ----------------- | -------------------------------------------- |
-| `children`    | `ReactNode`             | -                 | Child components                             |
-| `fen`         | `string`                | Starting position | Initial FEN string for the chess game        |
-| `orientation` | `"w" \| "b"`            | `"w"`             | Board orientation (white or black at bottom) |
-| `theme`       | `PartialChessGameTheme` | -                 | Optional theme configuration                 |
+| Name               | Type                    | Default           | Description                                              |
+| ------------------ | ----------------------- | ----------------- | -------------------------------------------------------- |
+| `children`         | `ReactNode`             | -                 | Child components                                         |
+| `fen`              | `string`                | Starting position | Initial FEN string for the chess game                    |
+| `orientation`      | `"w" \| "b"`            | `"w"`             | Board orientation (white or black at bottom)             |
+| `theme`            | `PartialChessGameTheme` | -                 | Optional theme configuration                             |
+| `timeControl`      | `TimeControlConfig`     | -                 | Optional clock configuration to enable chess clock       |
+| `autoSwitchOnMove` | `boolean`               | `true`            | Auto-switch clock on move (when timeControl is provided) |
 
 #### Example
 
@@ -103,6 +126,7 @@ The root component that provides `ChessGameContext` to all child components. It
 <ChessGame.Root
   fen="rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1"
   orientation="b"
+  timeControl={{ time: "10+5" }}
 >
   <ChessGame.Board />
 </ChessGame.Root>
@@ -207,6 +231,108 @@ Enables keyboard navigation through the game history.
 </ChessGame.Root>
 ```
 
+### ChessGame.Clock
+
+Integrated chess clock components. When `timeControl` is provided to `ChessGame.Root`, these components become available to display and control the clock.
+
+The clock automatically switches when moves are made on the board (can be disabled with `autoSwitchOnMove={false}`).
+
+**Note:** These are wrapper components that use the clock state from `ChessGame.Root`. No need for a separate `ChessClock.Root` provider.
+
+#### Available Components
+
+| Component                   | Description                                  |
+| --------------------------- | -------------------------------------------- |
+| `ChessGame.Clock.Display`   | Displays the current time for a player       |
+| `ChessGame.Clock.Switch`    | Button to manually switch the active clock   |
+| `ChessGame.Clock.PlayPause` | Button to start, pause, and resume the clock |
+| `ChessGame.Clock.Reset`     | Button to reset the clock                    |
+
+#### ChessGame.Clock.Display
+
+Displays the current time for a player.
+
+```tsx
+<ChessGame.Clock.Display
+  color="white"
+  format="auto"
+  style={{ fontFamily: "monospace", fontSize: "24px" }}
+/>
+```
+
+**Props:**
+
+| Name         | Type                                        | Default  | Description                        |
+| ------------ | ------------------------------------------- | -------- | ---------------------------------- |
+| `color`      | `"white" \| "black"`                        | -        | Player color to display (required) |
+| `format`     | `"auto" \| "mm:ss" \| "ss.d" \| "hh:mm:ss"` | `"auto"` | Time format                        |
+| `formatTime` | `(milliseconds: number) => string`          | -        | Custom time formatting function    |
+| `...`        | `HTMLAttributes<HTMLDivElement>`            | -        | All standard HTML div attributes   |
+
+#### ChessGame.Clock.Switch
+
+A button that manually switches the active player's clock.
+
+```tsx
+<ChessGame.Clock.Switch>Switch Turn</ChessGame.Clock.Switch>
+```
+
+**Props:**
+
+| Name      | Type                                      | Default | Description                            |
+| --------- | ----------------------------------------- | ------- | -------------------------------------- |
+| `asChild` | `boolean`                                 | `false` | Render as child element (slot pattern) |
+| `...`     | `ButtonHTMLAttributes<HTMLButtonElement>` | -       | All standard HTML button attributes    |
+
+#### ChessGame.Clock.PlayPause
+
+A button to start, pause, and resume the clock.
+
+```tsx
+<ChessGame.Clock.PlayPause
+  startContent="Start Game"
+  pauseContent="Pause"
+  resumeContent="Resume"
+/>
+```
+
+**Props:**
+
+| Name              | Type                                      | Default       | Description                            |
+| ----------------- | ----------------------------------------- | ------------- | -------------------------------------- |
+| `startContent`    | `ReactNode`                               | `"Start"`     | Content shown when clock is idle       |
+| `pauseContent`    | `ReactNode`                               | `"Pause"`     | Content shown when clock is running    |
+| `resumeContent`   | `ReactNode`                               | `"Resume"`    | Content shown when clock is paused     |
+| `delayedContent`  | `ReactNode`                               | `"Start"`     | Content shown when clock is delayed    |
+| `finishedContent` | `ReactNode`                               | `"Game Over"` | Content shown when clock is finished   |
+| `asChild`         | `boolean`                                 | `false`       | Render as child element (slot pattern) |
+| `...`             | `ButtonHTMLAttributes<HTMLButtonElement>` | -             | All standard HTML button attributes    |
+
+#### ChessGame.Clock.Reset
+
+A button that resets the clock.
+
+```tsx
+<ChessGame.Clock.Reset>Reset</ChessGame.Clock.Reset>;
+
+{
+  /* Reset with new time control */
+}
+<ChessGame.Clock.Reset timeControl="10+5">
+  Change to 10+5
+</ChessGame.Clock.Reset>;
+```
+
+**Props:**
+
+| Name          | Type                                      | Description                                   |
+| ------------- | ----------------------------------------- | --------------------------------------------- |
+| `timeControl` | `TimeControlInput`                        | New time control to apply on reset (optional) |
+| `asChild`     | `boolean`                                 | Render as child element (slot pattern)        |
+| `...`         | `ButtonHTMLAttributes<HTMLButtonElement>` | All standard HTML button attributes           |
+
+For more details on time control formats, timing methods, and clock start modes, see the [`@react-chess-tools/react-chess-clock` documentation](https://www.npmjs.com/package/@react-chess-tools/react-chess-clock).
+
 ## Hooks
 
 ### useChessGameContext
@@ -217,13 +343,14 @@ Access the chess game context from any child component.
 import { useChessGameContext } from "@react-chess-tools/react-chess-game";
 
 function GameStatus() {
-  const { currentFen, info, methods } = useChessGameContext();
+  const { currentFen, info, methods, clock } = useChessGameContext();
 
   return (
     <div>
       <p>Turn: {info.turn === "w" ? "White" : "Black"}</p>
       {info.isCheck && <p>Check!</p>}
       {info.isCheckmate && <p>Checkmate!</p>}
+      {clock && <p>White: {clock.times.white}ms</p>}
       <button onClick={() => methods.flipBoard()}>Flip Board</button>
     </div>
   );
@@ -232,16 +359,17 @@ function GameStatus() {
 
 #### Return Values
 
-| Name               | Type         | Description                         |
-| ------------------ | ------------ | ----------------------------------- |
-| `game`             | `Chess`      | The underlying chess.js instance    |
-| `orientation`      | `"w" \| "b"` | Current board orientation           |
-| `currentFen`       | `string`     | Current FEN string                  |
-| `currentPosition`  | `string`     | Current position in game history    |
-| `currentMoveIndex` | `number`     | Index of current move in history    |
-| `isLatestMove`     | `boolean`    | Whether viewing the latest position |
-| `methods`          | `Methods`    | Methods to interact with the game   |
-| `info`             | `Info`       | Game state information              |
+| Name               | Type                          | Description                           |
+| ------------------ | ----------------------------- | ------------------------------------- |
+| `game`             | `Chess`                       | The underlying chess.js instance      |
+| `orientation`      | `"w" \| "b"`                  | Current board orientation             |
+| `currentFen`       | `string`                      | Current FEN string                    |
+| `currentPosition`  | `string`                      | Current position in game history      |
+| `currentMoveIndex` | `number`                      | Index of current move in history      |
+| `isLatestMove`     | `boolean`                     | Whether viewing the latest position   |
+| `methods`          | `Methods`                     | Methods to interact with the game     |
+| `info`             | `Info`                        | Game state information                |
+| `clock`            | `UseChessClockReturn \| null` | Clock state (if timeControl provided) |
 
 #### Methods
 
@@ -294,6 +422,24 @@ function FullFeaturedGame() {
 }
 ```
 
+### Game with Chess Clock
+
+```tsx
+import { ChessGame } from "@react-chess-tools/react-chess-game";
+
+function GameWithClock() {
+  return (
+    <ChessGame.Root timeControl={{ time: "5+3" }}>
+      <ChessGame.Clock.Display color="white" />
+      <ChessGame.Board />
+      <ChessGame.Clock.Display color="black" />
+      <ChessGame.Clock.PlayPause />
+      <ChessGame.Clock.Reset>Reset</ChessGame.Clock.Reset>
+    </ChessGame.Root>
+  );
+}
+```
+
 ### Custom Starting Position
 
 ```tsx
@@ -390,6 +536,30 @@ function GameWithStatus() {
 }
 ```
 
+### Using ChessClock Directly
+
+You can also use `ChessClock` components directly alongside `ChessGame`:
+
+```tsx
+import { ChessGame, ChessClock } from "@react-chess-tools/react-chess-game";
+
+function GameWithSeparateClock() {
+  return (
+    <div>
+      <ChessClock.Root timeControl={{ time: "10+0" }}>
+        <ChessClock.Display color="white" />
+        <ChessClock.Display color="black" />
+        <ChessClock.PlayPause />
+      </ChessClock.Root>
+
+      <ChessGame.Root>
+        <ChessGame.Board />
+      </ChessGame.Root>
+    </div>
+  );
+}
+```
+
 ## License
 
 This project is [MIT](https://opensource.org/licenses/MIT) licensed.

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ChessClock: () => import_react_chess_clock3.ChessClock,
   ChessGame: () => ChessGame,
   ChessGameThemeContext: () => ChessGameThemeContext,
   chessComTheme: () => chessComTheme,
@@ -155,9 +156,12 @@ var getCurrentFen = (fen, game, currentMoveIndex) => {
 };
 
 // src/hooks/useChessGame.ts
+var import_react_chess_clock = require("@react-chess-tools/react-chess-clock");
 var useChessGame = ({
   fen,
-  orientation: initialOrientation
+  orientation: initialOrientation,
+  timeControl,
+  autoSwitchOnMove = true
 } = {}) => {
   const [game, setGame] = import_react.default.useState(() => {
     try {
@@ -180,22 +184,19 @@ var useChessGame = ({
   );
   const [currentMoveIndex, setCurrentMoveIndex] = import_react.default.useState(-1);
   const history = import_react.default.useMemo(() => game.history(), [game]);
-  const isLatestMove = import_react.default.useMemo(
-    () => currentMoveIndex === history.length - 1 || currentMoveIndex === -1,
-    [currentMoveIndex, history.length]
-  );
+  const isLatestMove = currentMoveIndex === history.length - 1 || currentMoveIndex === -1;
   const info = import_react.default.useMemo(
     () => getGameInfo(game, orientation),
     [game, orientation]
   );
   const currentFen = import_react.default.useMemo(
     () => getCurrentFen(fen, game, currentMoveIndex),
-    [game, currentMoveIndex]
-  );
-  const currentPosition = import_react.default.useMemo(
-    () => game.history()[currentMoveIndex],
-    [game, currentMoveIndex]
+    [fen, game, currentMoveIndex]
   );
+  const currentPosition = game.history()[currentMoveIndex];
+  const clockState = (0, import_react_chess_clock.useOptionalChessClock)(timeControl);
+  const clockStateRef = (0, import_react.useRef)(clockState);
+  clockStateRef.current = clockState;
   const setPosition = import_react.default.useCallback((fen2, orientation2) => {
     try {
       const newGame = new import_chess2.Chess();
@@ -212,17 +213,30 @@ var useChessGame = ({
       if (!isLatestMove) {
         return false;
       }
+      const clock = clockStateRef.current;
+      if (clock && clock.timeout !== null) {
+        return false;
+      }
       try {
         const copy = cloneGame(game);
         copy.move(move);
         setGame(copy);
         setCurrentMoveIndex(copy.history().length - 1);
+        if (clock && clock.status === "idle") {
+          clock.methods.start();
+        }
+        if (clock && clock.status === "running" && copy.isGameOver()) {
+          clock.methods.pause();
+        }
+        if (autoSwitchOnMove && clock && clock.status !== "finished") {
+          clock.methods.switch();
+        }
         return true;
       } catch (e) {
         return false;
       }
     },
-    [isLatestMove, game]
+    [isLatestMove, game, autoSwitchOnMove]
   );
   const flipBoard = import_react.default.useCallback(() => {
     setOrientation((orientation2) => orientation2 === "w" ? "b" : "w");
@@ -277,7 +291,8 @@ var useChessGame = ({
     currentMoveIndex,
     isLatestMove,
     info,
-    methods
+    methods,
+    clock: clockState
   };
 };
 
@@ -347,9 +362,16 @@ var Root = ({
   fen,
   orientation,
   theme,
+  timeControl,
+  autoSwitchOnMove,
   children
 }) => {
-  const context = useChessGame({ fen, orientation });
+  const context = useChessGame({
+    fen,
+    orientation,
+    timeControl,
+    autoSwitchOnMove
+  });
   const mergedTheme = import_react4.default.useMemo(() => mergeTheme(theme), [theme]);
   return /* @__PURE__ */ import_react4.default.createElement(ChessGameContext.Provider, { value: context }, /* @__PURE__ */ import_react4.default.createElement(ThemeProvider, { theme: mergedTheme }, children));
 };
@@ -719,14 +741,62 @@ var KeyboardControls2 = ({
 };
 KeyboardControls2.displayName = "ChessGame.KeyboardControls";
 
+// src/components/ChessGame/Clock/index.tsx
+var import_react9 = __toESM(require("react"), 1);
+var import_react_chess_clock2 = require("@react-chess-tools/react-chess-clock");
+var Display = import_react9.default.forwardRef(
+  ({ color, ...rest }, ref) => {
+    const { clock } = useChessGameContext();
+    if (!clock) {
+      return null;
+    }
+    return /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.ChessClockContext.Provider, { value: clock }, /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.Display, { ref, color, ...rest }));
+  }
+);
+Display.displayName = "ChessGame.Clock.Display";
+var Switch = import_react9.default.forwardRef(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+  if (!clock) {
+    return null;
+  }
+  return /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.ChessClockContext.Provider, { value: clock }, /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.Switch, { ref, ...rest }, children));
+});
+Switch.displayName = "ChessGame.Clock.Switch";
+var PlayPause = import_react9.default.forwardRef(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+  if (!clock) {
+    return null;
+  }
+  return /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.ChessClockContext.Provider, { value: clock }, /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.PlayPause, { ref, ...rest }, children));
+});
+PlayPause.displayName = "ChessGame.Clock.PlayPause";
+var Reset = import_react9.default.forwardRef(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+  if (!clock) {
+    return null;
+  }
+  return /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.ChessClockContext.Provider, { value: clock }, /* @__PURE__ */ import_react9.default.createElement(import_react_chess_clock2.Reset, { ref, ...rest }, children));
+});
+Reset.displayName = "ChessGame.Clock.Reset";
+var Clock = {
+  Display,
+  Switch,
+  PlayPause,
+  Reset
+};
+
 // src/components/ChessGame/index.ts
 var ChessGame = {
   Root,
   Board,
   Sounds,
-  KeyboardControls: KeyboardControls2
+  KeyboardControls: KeyboardControls2,
+  Clock
 };
 
+// src/index.ts
+var import_react_chess_clock3 = require("@react-chess-tools/react-chess-clock");
+
 // src/theme/presets.ts
 var lichessTheme = {
   board: {
@@ -769,6 +839,7 @@ var themes = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ChessClock,
   ChessGame,
   ChessGameThemeContext,
   chessComTheme,