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

package/src/components/ChessPuzzle/parts/__tests__/Reset.test.tsx

@@ -0,0 +1,341 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessPuzzle } from "../..";
+import { Reset } from "../Reset";
+import { Puzzle } from "../../../../utils";
+
+describe("ChessPuzzle.Reset", () => {
+  const mockPuzzle: Puzzle = {
+    fen: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+    moves: ["e4", "e5"],
+  };
+
+  describe("displayName", () => {
+    it("should have correct displayName", () => {
+      expect(Reset.displayName).toBe("ChessPuzzle.Reset");
+    });
+  });
+
+  describe("ref forwarding", () => {
+    it("should forward ref to button element", () => {
+      const ref = React.createRef<HTMLElement>();
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset
+            ref={ref}
+            showOn={["not-started", "in-progress", "failed", "solved"]}
+          />
+        </ChessPuzzle.Root>,
+      );
+
+      expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+    });
+
+    it("should forward ref when using asChild", () => {
+      const ref = React.createRef<HTMLElement>();
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset
+            ref={ref}
+            asChild
+            showOn={["not-started", "in-progress", "failed", "solved"]}
+          >
+            <button>Custom Reset</button>
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+    });
+
+    it("should support callback refs", () => {
+      let capturedRef: HTMLElement | null = null;
+      const callbackRef = (ref: HTMLElement | null) => {
+        capturedRef = ref;
+      };
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset
+            ref={callbackRef}
+            showOn={["not-started", "in-progress", "failed", "solved"]}
+          />
+        </ChessPuzzle.Root>,
+      );
+
+      expect(capturedRef).toBeInstanceOf(HTMLButtonElement);
+    });
+  });
+
+  describe("visibility based on showOn prop", () => {
+    it("should be visible when status matches showOn", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]}>Reset</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toBeInTheDocument();
+    });
+
+    it("should be hidden when status does not match showOn", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["solved"]}>Reset</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    it("should default to showing on failed and solved statuses", () => {
+      // Default showOn is ["failed", "solved"], so it should be hidden at start
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset>Reset</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    it("should accept multiple statuses in showOn", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started", "in-progress", "failed", "solved"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toBeInTheDocument();
+    });
+  });
+
+  describe("prop spreading", () => {
+    it("should apply custom className", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset className="custom-reset-class" showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toHaveClass("custom-reset-class");
+    });
+
+    it("should apply custom id", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset id="reset-button" showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toHaveAttribute("id", "reset-button");
+    });
+
+    it("should apply data-* attributes", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset
+            data-testid="reset"
+            data-custom="value"
+            showOn={["not-started"]}
+          >
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      const button = screen.getByTestId("reset");
+      expect(button).toHaveAttribute("data-custom", "value");
+    });
+
+    it("should apply aria-* attributes", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset aria-label="Reset puzzle" showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toHaveAttribute(
+        "aria-label",
+        "Reset puzzle",
+      );
+    });
+
+    it("should apply disabled attribute", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset disabled showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toBeDisabled();
+    });
+  });
+
+  describe("asChild pattern", () => {
+    it("should render custom element when asChild is true", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset asChild showOn={["not-started"]}>
+            <button className="custom-button">Custom Reset</button>
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      const button = screen.getByRole("button");
+      expect(button).toHaveTextContent("Custom Reset");
+      expect(button).toHaveClass("custom-button");
+    });
+
+    it("should merge className with asChild element", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset asChild className="reset-class" showOn={["not-started"]}>
+            <button className="child-class">Reset</button>
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      const button = screen.getByRole("button");
+      expect(button).toHaveClass("reset-class");
+      expect(button).toHaveClass("child-class");
+    });
+
+    it("should compose onClick handlers with asChild", () => {
+      const childOnClick = jest.fn();
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset asChild showOn={["not-started"]}>
+            <button onClick={childOnClick}>Reset</button>
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      fireEvent.click(screen.getByRole("button"));
+      expect(childOnClick).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("functionality", () => {
+    it("should call onReset callback when clicked", () => {
+      const handleReset = jest.fn();
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset onReset={handleReset} showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      fireEvent.click(screen.getByRole("button"));
+      expect(handleReset).toHaveBeenCalledTimes(1);
+    });
+
+    it("should pass puzzle context to onReset callback", () => {
+      const handleReset = jest.fn();
+
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset onReset={handleReset} showOn={["not-started"]}>
+            Reset
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      fireEvent.click(screen.getByRole("button"));
+      expect(handleReset).toHaveBeenCalledWith(
+        expect.objectContaining({
+          puzzle: mockPuzzle,
+          status: expect.any(String),
+          changePuzzle: expect.any(Function),
+        }),
+      );
+    });
+
+    it("should have type button by default", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]}>Reset</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toHaveAttribute("type", "button");
+    });
+  });
+
+  describe("context validation", () => {
+    it("should throw error when used outside ChessPuzzle.Root", () => {
+      const consoleError = jest
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+
+      expect(() => {
+        render(<Reset showOn={["not-started"]}>Reset</Reset>);
+      }).toThrow();
+
+      consoleError.mockRestore();
+    });
+  });
+
+  describe("children", () => {
+    it("should render text children", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]}>Reset Puzzle</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toHaveTextContent("Reset Puzzle");
+    });
+
+    it("should render element children", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]}>
+            <span data-testid="child">Reset Icon</span>
+          </Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByTestId("child")).toBeInTheDocument();
+    });
+
+    it("should render without children", () => {
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]} aria-label="Reset" />
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toBeInTheDocument();
+    });
+  });
+
+  describe("backward compatibility", () => {
+    it("should work with minimal props when status matches default showOn", () => {
+      // Since default showOn is ["failed", "solved"], we need to set showOn to see the button
+      render(
+        <ChessPuzzle.Root puzzle={mockPuzzle}>
+          <Reset showOn={["not-started"]}>Reset</Reset>
+        </ChessPuzzle.Root>,
+      );
+
+      expect(screen.getByRole("button")).toBeInTheDocument();
+    });
+  });
+});

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

@@ -0,0 +1,42 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessPuzzle } from "../..";
+import { Root } from "../Root";
+import { Puzzle } from "../../../../utils";
+
+describe("ChessPuzzle.Root", () => {
+  const mockPuzzle: Puzzle = {
+    fen: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+    moves: ["e4", "e5"],
+  };
+
+  it("should have correct displayName", () => {
+    expect(Root.displayName).toBe("ChessPuzzle.Root");
+  });
+
+  it("should render children correctly", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <div data-testid="child">Child Component</div>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(screen.getByText("Child Component")).toBeInTheDocument();
+  });
+
+  it("should render multiple children", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <div data-testid="child-1">Child 1</div>
+        <div data-testid="child-2">Child 2</div>
+        <div data-testid="child-3">Child 3</div>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByTestId("child-1")).toBeInTheDocument();
+    expect(screen.getByTestId("child-2")).toBeInTheDocument();
+    expect(screen.getByTestId("child-3")).toBeInTheDocument();
+  });
+});

package/src/hooks/__tests__/reducer.test.ts

@@ -271,4 +271,138 @@ describe("reducer", () => {
       expect(newState.status).toBe("failed");
     });
   });
+
+  describe("solveOnCheckmate feature", () => {
+    // Puzzle with multiple checkmate solutions
+    const multiMatePuzzle: Puzzle = {
+      fen: "7k/R7/1R6/2Q5/4Q3/8/8/7K w - - 0 1",
+      moves: ["a7a8"],
+      makeFirstMove: false,
+    };
+
+    const multiMateInitialState: State = {
+      puzzle: multiMatePuzzle,
+      currentMoveIndex: 0,
+      status: "not-started",
+      nextMove: "a7a8",
+      hint: "none",
+      cpuMove: null,
+      needCpuMove: false,
+      isPlayerTurn: true,
+      onSolveInvoked: false,
+      onFailInvoked: false,
+    };
+
+    it("should solve puzzle when alternative checkmate move is made and solveOnCheckmate=true", () => {
+      const game = new Chess(multiMatePuzzle.fen);
+      // Alternative mate: Qc8# (queen mate from c5 to c8) instead of canonical Ra8#
+      game.move("Qc8");
+      const alternativeMateMove = game.history({ verbose: true }).pop() as Move;
+
+      const action: Action = {
+        type: "PLAYER_MOVE",
+        payload: {
+          move: alternativeMateMove,
+          puzzleContext: {} as ChessPuzzleContextType,
+          game,
+          solveOnCheckmate: true,
+        },
+      };
+
+      const newState = reducer(multiMateInitialState, action);
+
+      expect(newState.status).toBe("solved");
+      expect(newState.nextMove).toBe(null);
+      expect(newState.isPlayerTurn).toBe(false);
+    });
+
+    it("should fail puzzle when alternative checkmate move is made and solveOnCheckmate=false", () => {
+      const game = new Chess(multiMatePuzzle.fen);
+      // Alternative mate: Qf8# (queen mate from c5 to f8) instead of canonical Ra8#
+      game.move("Qf8");
+      const alternativeMateMove = game.history({ verbose: true }).pop() as Move;
+
+      const action: Action = {
+        type: "PLAYER_MOVE",
+        payload: {
+          move: alternativeMateMove,
+          puzzleContext: {} as ChessPuzzleContextType,
+          game,
+          solveOnCheckmate: false,
+        },
+      };
+
+      const newState = reducer(multiMateInitialState, action);
+
+      expect(newState.status).toBe("failed");
+      expect(newState.nextMove).toBe(null);
+    });
+
+    it("should still solve puzzle when canonical solution move is made with solveOnCheckmate=true", () => {
+      const game = new Chess(multiMatePuzzle.fen);
+      // Make the canonical checkmate move on the game so isCheckmate() returns true
+      game.move("a7a8");
+      // Canonical move: Ra8# (rook mate from b6 to b8)
+      const canonicalMove = game.history({ verbose: true }).pop() as Move;
+
+      const action: Action = {
+        type: "PLAYER_MOVE",
+        payload: {
+          move: canonicalMove,
+          puzzleContext: {} as ChessPuzzleContextType,
+          game,
+          solveOnCheckmate: true,
+        },
+      };
+
+      const newState = reducer(multiMateInitialState, action);
+
+      expect(newState.status).toBe("solved");
+      expect(newState.nextMove).toBe(null);
+    });
+
+    it("should fail puzzle when non-mate incorrect move is made with solveOnCheckmate=true", () => {
+      const game = new Chess(multiMatePuzzle.fen);
+      // Make a non-mate incorrect move (Qa3 checks but doesn't mate)
+      const incorrectResult = game.move("Qa3");
+      const incorrectMove = incorrectResult as Move;
+
+      const action: Action = {
+        type: "PLAYER_MOVE",
+        payload: {
+          move: incorrectMove,
+          puzzleContext: {} as ChessPuzzleContextType,
+          game,
+          solveOnCheckmate: true,
+        },
+      };
+
+      const newState = reducer(multiMateInitialState, action);
+
+      // Not a checkmate (Qa3 is not mate), so should fail as incorrect move
+      expect(newState.status).toBe("failed");
+    });
+
+    it("should enable checkmate detection when solveOnCheckmate is undefined in payload", () => {
+      const game = new Chess(multiMatePuzzle.fen);
+      // Make an alternative checkmate move on the game so isCheckmate() returns true
+      game.move("Qe8");
+      // Alternative mate: Qe8# (queen mate from e4 to e8)
+      const alternativeMateMove = game.history({ verbose: true }).pop() as Move;
+
+      const action: Action = {
+        type: "PLAYER_MOVE",
+        payload: {
+          move: alternativeMateMove,
+          puzzleContext: {} as ChessPuzzleContextType,
+          game,
+          // solveOnCheckmate not provided - should default to true
+        },
+      };
+
+      const newState = reducer(multiMateInitialState, action);
+
+      expect(newState.status).toBe("solved");
+    });
+  });
 });

package/src/hooks/reducer.ts

@@ -35,6 +35,7 @@ export type Action =
         move?: Move | null;
         puzzleContext: ChessPuzzleContextType;
         game: Chess;
+        solveOnCheckmate?: boolean;
       };
     }
   | { type: "MARK_SOLVE_INVOKED" }
@@ -96,7 +97,18 @@ export const reducer = (state: State, action: Action): State => {
       };
 
     case "PLAYER_MOVE": {
-      const { move } = action.payload;
+      const { move, game, solveOnCheckmate } = action.payload;
+
+      if (move && solveOnCheckmate !== false && game.isCheckmate()) {
+        return {
+          ...state,
+          status: "solved",
+          nextMove: null,
+          hint: "none",
+          isPlayerTurn: false,
+          onSolveInvoked: false,
+        };
+      }
 
       const isMoveRight = [move?.san, move?.lan].includes(
         state?.nextMove || "",

package/src/hooks/useChessPuzzle.ts

@@ -21,6 +21,7 @@ export const useChessPuzzle = (
   puzzle: Puzzle,
   onSolve?: (puzzleContext: ChessPuzzleContextType) => void,
   onFail?: (puzzleContext: ChessPuzzleContextType) => void,
+  solveOnCheckmate: boolean = true,
 ): ChessPuzzleContextType => {
   const gameContext = useChessGameContext();
 
@@ -111,6 +112,7 @@ export const useChessPuzzle = (
           move: gameContext?.game?.history({ verbose: true })?.pop() ?? null,
           puzzleContext,
           game: game,
+          solveOnCheckmate,
         },
       });
 

package/src/utils/__tests__/index.test.ts

@@ -1,8 +1,6 @@
 import { Chess, Move } from "chess.js";
-import React from "react";
 import {
   getOrientation,
-  isClickableElement,
   getCustomSquareStyles,
   stringToMove,
   Puzzle,
@@ -40,21 +38,6 @@ describe("Puzzle Utilities", () => {
     });
   });
 
-  describe("isClickableElement", () => {
-    it("should return true for valid clickable elements", () => {
-      const clickableElement = React.createElement("button", {
-        onClick: () => {},
-      });
-      expect(isClickableElement(clickableElement)).toBe(true);
-    });
-
-    it("should return false for non-React elements", () => {
-      expect(isClickableElement("not an element")).toBe(false);
-      expect(isClickableElement(null)).toBe(false);
-      expect(isClickableElement(undefined)).toBe(false);
-    });
-  });
-
   describe("getCustomSquareStyles", () => {
     const game = new Chess();
 

package/src/utils/index.ts

@@ -1,5 +1,5 @@
 import { type Color, Chess, Move } from "chess.js";
-import React, { CSSProperties, ReactElement, ReactNode } from "react";
+import { type CSSProperties } from "react";
 import _ from "lodash";
 import type { ChessPuzzleTheme } from "../theme/types";
 import { defaultPuzzleTheme } from "../theme/defaults";
@@ -24,16 +24,6 @@ export const getOrientation = (puzzle: Puzzle): Color => {
   return game.turn();
 };
 
-interface ClickableElement extends ReactElement {
-  props: {
-    onClick?: () => void;
-  };
-}
-
-export const isClickableElement = (
-  element: ReactNode,
-): element is ClickableElement => React.isValidElement(element);
-
 /**
  * Generates custom square styles for puzzle states based on theme.
  *