@react-chess-tools/react-chess-game 1.0.0 → 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/Theme.stories.tsx

@@ -1,8 +1,8 @@
-import type { Meta, StoryObj } from "@storybook/react";
+import type { Meta } from "@storybook/react";
 import React, { useState } from "react";
 import { ChessGame } from "./index";
 import { defaultGameTheme, themes } from "../../theme";
-import type { ChessGameTheme, PartialChessGameTheme } from "../../theme/types";
+import type { ChessGameTheme } from "../../theme/types";
 
 const meta = {
   title: "react-chess-game/Theme/Playground",

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/Board.tsx

@@ -14,229 +14,238 @@ 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();
-  const theme = useChessGameTheme();
+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, 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);
-
-  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";