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

package/src/components/ChessGame/Clock/index.tsx

@@ -0,0 +1,174 @@
+import React from "react";
+import { useChessGameContext } from "../../../hooks/useChessGameContext";
+import {
+  Display as ClockDisplay,
+  Switch as ClockSwitch,
+  PlayPause as ClockPlayPause,
+  Reset as ClockReset,
+  ChessClockContext,
+} from "@react-chess-tools/react-chess-clock";
+import type {
+  ChessClockDisplayProps,
+  ChessClockControlProps,
+  ChessClockPlayPauseProps,
+  ChessClockResetProps,
+  ClockColor,
+} from "@react-chess-tools/react-chess-clock";
+
+export type {
+  ChessClockDisplayProps,
+  ChessClockControlProps,
+  ChessClockPlayPauseProps,
+  ChessClockResetProps,
+  ClockColor,
+} from "@react-chess-tools/react-chess-clock";
+
+export interface ClockDisplayProps extends Omit<
+  ChessClockDisplayProps,
+  "color"
+> {
+  color: ClockColor;
+}
+
+/**
+ * ChessGame.Clock.Display - Autonomous display component
+ *
+ * Wraps react-chess-clock's Display component, providing clock state from ChessGame.Root context.
+ * No need to pass timeControl - it's inherited from the root.
+ *
+ * @example
+ * ```tsx
+ * <ChessGame.Root timeControl={{ time: "5+3" }}>
+ *   <ChessGame.Clock.Display color="white" />
+ *   <ChessGame.Board />
+ *   <ChessGame.Clock.Display color="black" />
+ * </ChessGame.Root>
+ * ```
+ */
+export const Display = React.forwardRef<HTMLDivElement, ClockDisplayProps>(
+  ({ color, ...rest }, ref) => {
+    const { clock } = useChessGameContext();
+
+    if (!clock) {
+      return null;
+    }
+
+    return (
+      <ChessClockContext.Provider value={clock}>
+        <ClockDisplay ref={ref} color={color} {...rest} />
+      </ChessClockContext.Provider>
+    );
+  },
+);
+
+Display.displayName = "ChessGame.Clock.Display";
+
+/**
+ * ChessGame.Clock.Switch - Manual switch control
+ *
+ * Wraps react-chess-clock's Switch component, providing clock state from ChessGame.Root context.
+ *
+ * @example
+ * ```tsx
+ * <ChessGame.Root timeControl={{ time: "5+3" }}>
+ *   <ChessGame.Clock.Switch>Switch Clock</ChessGame.Clock.Switch>
+ * </ChessGame.Root>
+ * ```
+ */
+export const Switch = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockControlProps>
+>(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+
+  if (!clock) {
+    return null;
+  }
+
+  return (
+    <ChessClockContext.Provider value={clock}>
+      <ClockSwitch ref={ref} {...rest}>
+        {children}
+      </ClockSwitch>
+    </ChessClockContext.Provider>
+  );
+});
+
+Switch.displayName = "ChessGame.Clock.Switch";
+
+/**
+ * ChessGame.Clock.PlayPause - Play/pause control
+ *
+ * Wraps react-chess-clock's PlayPause component, providing clock state from ChessGame.Root context.
+ *
+ * @example
+ * ```tsx
+ * <ChessGame.Root timeControl={{ time: "5+3" }}>
+ *   <ChessGame.Clock.PlayPause
+ *     startContent="Start"
+ *     pauseContent="Pause"
+ *     resumeContent="Resume"
+ *   />
+ * </ChessGame.Root>
+ * ```
+ */
+export const PlayPause = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockPlayPauseProps>
+>(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+
+  if (!clock) {
+    return null;
+  }
+
+  return (
+    <ChessClockContext.Provider value={clock}>
+      <ClockPlayPause ref={ref} {...rest}>
+        {children}
+      </ClockPlayPause>
+    </ChessClockContext.Provider>
+  );
+});
+
+PlayPause.displayName = "ChessGame.Clock.PlayPause";
+
+/**
+ * ChessGame.Clock.Reset - Reset control
+ *
+ * Wraps react-chess-clock's Reset component, providing clock state from ChessGame.Root context.
+ *
+ * @example
+ * ```tsx
+ * <ChessGame.Root timeControl={{ time: "5+3" }}>
+ *   <ChessGame.Clock.Reset>Reset</ChessGame.Clock.Reset>
+ * </ChessGame.Root>
+ * ```
+ */
+export const Reset = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockResetProps>
+>(({ children, ...rest }, ref) => {
+  const { clock } = useChessGameContext();
+
+  if (!clock) {
+    return null;
+  }
+
+  return (
+    <ChessClockContext.Provider value={clock}>
+      <ClockReset ref={ref} {...rest}>
+        {children}
+      </ClockReset>
+    </ChessClockContext.Provider>
+  );
+});
+
+Reset.displayName = "ChessGame.Clock.Reset";
+
+export const Clock = {
+  Display,
+  Switch,
+  PlayPause,
+  Reset,
+};

package/src/components/ChessGame/index.ts

@@ -2,10 +2,12 @@ import { Root } from "./parts/Root";
 import { Board } from "./parts/Board";
 import { Sounds } from "./parts/Sounds";
 import { KeyboardControls } from "./parts/KeyboardControls";
+import { Clock } from "./Clock";
 
 export const ChessGame = {
   Root,
   Board,
   Sounds,
   KeyboardControls,
+  Clock,
 };

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]);

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";