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

package/src/components/ChessPuzzle/parts/Hint.tsx

@@ -1,46 +1,55 @@
 import React from "react";
-import { Status, isClickableElement } from "../../../utils";
+import { Slot } from "@radix-ui/react-slot";
+import { Status } from "../../../utils";
 import { useChessPuzzleContext } from "../../..";
 
-export interface HintProps {
+export interface HintProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> {
   asChild?: boolean;
+  /**
+   * The puzzle statuses in which the hint button should be visible.
+   * @default ["not-started", "in-progress"]
+   */
   showOn?: Status[];
 }
 
 const defaultShowOn: Status[] = ["not-started", "in-progress"];
 
-export const Hint: React.FC<React.PropsWithChildren<HintProps>> = ({
-  children,
-  asChild,
-  showOn = defaultShowOn,
-}) => {
+export const Hint = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<HintProps>
+>(({ children, asChild, showOn = defaultShowOn, className, ...rest }, ref) => {
   const puzzleContext = useChessPuzzleContext();
   if (!puzzleContext) {
     throw new Error("PuzzleContext not found");
   }
   const { onHint, status } = puzzleContext;
-  const handleClick = () => {
+
+  const handleClick = React.useCallback(() => {
     onHint();
-  };
+  }, [onHint]);
 
   if (!showOn.includes(status)) {
     return null;
   }
 
-  if (asChild) {
-    const child = React.Children.only(children);
-    if (isClickableElement(child)) {
-      return React.cloneElement(child, {
-        onClick: handleClick,
-      });
-    } else {
-      throw new Error("Change child must be a clickable element");
-    }
-  }
-
-  return (
-    <button type="button" onClick={handleClick}>
+  return asChild ? (
+    <Slot ref={ref} onClick={handleClick} className={className} {...rest}>
+      {children}
+    </Slot>
+  ) : (
+    <button
+      ref={ref as React.RefObject<HTMLButtonElement>}
+      type="button"
+      className={className}
+      onClick={handleClick}
+      {...rest}
+    >
       {children}
     </button>
   );
-};
+});
+
+Hint.displayName = "ChessPuzzle.Hint";

package/src/components/ChessPuzzle/parts/PuzzleBoard.tsx

@@ -12,34 +12,35 @@ export interface PuzzleBoardProps extends React.ComponentProps<
   typeof ChessGame.Board
 > {}
 
-export const PuzzleBoard: React.FC<PuzzleBoardProps> = ({
-  options = {},
-  ...rest
-}) => {
-  const puzzleContext = useChessPuzzleContext();
-  const gameContext = useChessGameContext();
-  const theme = useChessPuzzleTheme();
+export const PuzzleBoard = React.forwardRef<HTMLDivElement, PuzzleBoardProps>(
+  ({ options, ...rest }, ref) => {
+    const puzzleContext = useChessPuzzleContext();
+    const gameContext = useChessGameContext();
+    const theme = useChessPuzzleTheme();
 
-  if (!puzzleContext) {
-    throw new Error("PuzzleContext not found");
-  }
-  if (!gameContext) {
-    throw new Error("ChessGameContext not found");
-  }
+    if (!puzzleContext) {
+      throw new Error("PuzzleContext not found");
+    }
+    if (!gameContext) {
+      throw new Error("ChessGameContext not found");
+    }
 
-  const { game } = gameContext;
-  const { status, hint, isPlayerTurn, nextMove } = puzzleContext;
+    const { game } = gameContext;
+    const { status, hint, isPlayerTurn, nextMove } = puzzleContext;
 
-  const mergedOptions = deepMergeChessboardOptions(options, {
-    squareStyles: getCustomSquareStyles(
-      status,
-      hint,
-      isPlayerTurn,
-      game,
-      stringToMove(game, nextMove),
-      theme,
-    ),
-  });
+    const mergedOptions = deepMergeChessboardOptions(options || {}, {
+      squareStyles: getCustomSquareStyles(
+        status,
+        hint,
+        isPlayerTurn,
+        game,
+        stringToMove(game, nextMove),
+        theme,
+      ),
+    });
 
-  return <ChessGame.Board {...rest} options={mergedOptions} />;
-};
+    return <ChessGame.Board ref={ref} {...rest} options={mergedOptions} />;
+  },
+);
+
+PuzzleBoard.displayName = "ChessPuzzle.PuzzleBoard";

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

@@ -1,51 +1,71 @@
 import React from "react";
-import { isClickableElement, type Puzzle, type Status } from "../../../utils";
+import { Slot } from "@radix-ui/react-slot";
+import { type Puzzle, type Status } from "../../../utils";
 import { useChessPuzzleContext, type ChessPuzzleContextType } from "../../..";
 
-export interface ResetProps {
+export interface ResetProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onReset"
+> {
   asChild?: boolean;
   puzzle?: Puzzle;
   onReset?: (puzzleContext: ChessPuzzleContextType) => void;
+  /**
+   * The puzzle statuses in which the reset button should be visible.
+   * @default ["failed", "solved"]
+   */
   showOn?: Status[];
 }
 
 const defaultShowOn: Status[] = ["failed", "solved"];
 
-export const Reset: React.FC<React.PropsWithChildren<ResetProps>> = ({
-  children,
-  asChild,
-  puzzle,
-  onReset,
-  showOn = defaultShowOn,
-}) => {
-  const puzzleContext = useChessPuzzleContext();
-  if (!puzzleContext) {
-    throw new Error("PuzzleContext not found");
-  }
-  const { changePuzzle, status } = puzzleContext;
-  const handleClick = () => {
-    changePuzzle(puzzle || puzzleContext.puzzle);
-    onReset?.(puzzleContext);
-  };
+export const Reset = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ResetProps>
+>(
+  (
+    {
+      children,
+      asChild,
+      puzzle,
+      onReset,
+      showOn = defaultShowOn,
+      className,
+      ...rest
+    },
+    ref,
+  ) => {
+    const puzzleContext = useChessPuzzleContext();
+    if (!puzzleContext) {
+      throw new Error("PuzzleContext not found");
+    }
+    const { changePuzzle, puzzle: contextPuzzle, status } = puzzleContext;
 
-  if (!showOn.includes(status)) {
-    return null;
-  }
+    const handleClick = React.useCallback(() => {
+      changePuzzle(puzzle || contextPuzzle);
+      onReset?.(puzzleContext);
+    }, [changePuzzle, puzzle, contextPuzzle, puzzleContext, onReset]);
 
-  if (asChild) {
-    const child = React.Children.only(children);
-    if (isClickableElement(child)) {
-      return React.cloneElement(child, {
-        onClick: handleClick,
-      });
-    } else {
-      throw new Error("Change child must be a clickable element");
+    if (!showOn.includes(status)) {
+      return null;
     }
-  }
 
-  return (
-    <button type="button" onClick={handleClick}>
-      {children}
-    </button>
-  );
-};
+    return asChild ? (
+      <Slot ref={ref} onClick={handleClick} className={className} {...rest}>
+        {children}
+      </Slot>
+    ) : (
+      <button
+        ref={ref as React.RefObject<HTMLButtonElement>}
+        type="button"
+        className={className}
+        onClick={handleClick}
+        {...rest}
+      >
+        {children}
+      </button>
+    );
+  },
+);
+
+Reset.displayName = "ChessPuzzle.Reset";

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

@@ -16,12 +16,15 @@ export interface RootProps {
   onFail?: (puzzleContext: ChessPuzzleContextType) => void;
   /** Optional theme configuration. Supports partial themes - only override the colors you need. */
   theme?: PartialChessPuzzleTheme;
+  /** When true, any checkmate move solves the puzzle (not just the canonical solution). Defaults to true. */
+  solveOnCheckmate?: boolean;
 }
 
 interface PuzzleRootInnerProps {
   puzzle: Puzzle;
   onSolve?: (puzzleContext: ChessPuzzleContextType) => void;
   onFail?: (puzzleContext: ChessPuzzleContextType) => void;
+  solveOnCheckmate: boolean;
   children: React.ReactNode;
 }
 
@@ -29,9 +32,10 @@ const PuzzleRootInner: React.FC<PuzzleRootInnerProps> = ({
   puzzle,
   onSolve,
   onFail,
+  solveOnCheckmate,
   children,
 }) => {
-  const context = useChessPuzzle(puzzle, onSolve, onFail);
+  const context = useChessPuzzle(puzzle, onSolve, onFail, solveOnCheckmate);
 
   return (
     <ChessPuzzleContext.Provider value={context}>
@@ -45,6 +49,7 @@ export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
   onSolve,
   onFail,
   theme,
+  solveOnCheckmate = true,
   children,
 }) => {
   // Merge partial theme with defaults
@@ -57,10 +62,17 @@ export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
       theme={mergedTheme}
     >
       <PuzzleThemeProvider theme={mergedTheme}>
-        <PuzzleRootInner puzzle={puzzle} onSolve={onSolve} onFail={onFail}>
+        <PuzzleRootInner
+          puzzle={puzzle}
+          onSolve={onSolve}
+          onFail={onFail}
+          solveOnCheckmate={solveOnCheckmate}
+        >
           {children}
         </PuzzleRootInner>
       </PuzzleThemeProvider>
     </ChessGame.Root>
   );
 };
+
+Root.displayName = "ChessPuzzle.Root";

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

@@ -0,0 +1,158 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessPuzzle } from "../..";
+import { Hint } from "../Hint";
+import { Puzzle } from "../../../../utils";
+
+describe("ChessPuzzle.Hint", () => {
+  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(Hint.displayName).toBe("ChessPuzzle.Hint");
+  });
+
+  it("should forward ref to button element", () => {
+    const ref = React.createRef<HTMLElement>();
+
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint ref={ref} />
+      </ChessPuzzle.Root>,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  it("should forward ref when using asChild", () => {
+    const ref = React.createRef<HTMLElement>();
+
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint ref={ref} asChild>
+          <button>Custom Hint</button>
+        </Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  it("should be visible when status matches showOn", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint showOn={["not-started"]}>Hint</Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("should be hidden when status does not match showOn", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint showOn={["solved"]}>Hint</Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+
+  it("should default to showing on not-started and in-progress statuses", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint>Hint</Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("should accept multiple statuses in showOn", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint showOn={["not-started", "in-progress", "failed", "solved"]}>
+          Hint
+        </Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("should render custom element when asChild is true", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint asChild>
+          <button className="custom-button">Custom Hint</button>
+        </Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).toHaveTextContent("Custom Hint");
+    expect(button).toHaveClass("custom-button");
+  });
+
+  it("should compose onClick handlers with asChild", () => {
+    const childOnClick = jest.fn();
+
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint asChild>
+          <button onClick={childOnClick}>Hint</button>
+        </Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    fireEvent.click(screen.getByRole("button"));
+    expect(childOnClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("should throw error when used outside ChessPuzzle.Root", () => {
+    const consoleError = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() => {
+      render(<Hint>Hint</Hint>);
+    }).toThrow();
+
+    consoleError.mockRestore();
+  });
+
+  it("should render text children", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint>Show Hint</Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByRole("button")).toHaveTextContent("Show Hint");
+  });
+
+  it("should render element children", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint>
+          <span data-testid="child">Hint Icon</span>
+        </Hint>
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+  });
+
+  it("should render without children", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <Hint aria-label="Show hint" />
+      </ChessPuzzle.Root>,
+    );
+
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,140 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { ChessPuzzle } from "../..";
+import { PuzzleBoard } from "../PuzzleBoard";
+import { Puzzle } from "../../../../utils";
+import { ChessGame } from "@react-chess-tools/react-chess-game";
+
+describe("ChessPuzzle.PuzzleBoard", () => {
+  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(PuzzleBoard.displayName).toBe("ChessPuzzle.PuzzleBoard");
+  });
+
+  it("should forward ref to underlying Board component", () => {
+    const ref = React.createRef<HTMLDivElement>();
+
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard ref={ref} />
+      </ChessPuzzle.Root>,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it("should allow focusing via ref", () => {
+    const ref = React.createRef<HTMLDivElement>();
+
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard ref={ref} tabIndex={0} />
+      </ChessPuzzle.Root>,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+
+    // Note: focus() doesn't work in JSDOM, but we can verify the ref points to the element
+    // In a real browser, ref.current?.focus() would set document.activeElement to ref.current
+  });
+
+  it("should apply custom className", () => {
+    const { container } = render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard className="custom-puzzle-board-class" />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = container.querySelector('[style*="position: relative"]');
+    expect(board).toHaveClass("custom-puzzle-board-class");
+  });
+
+  it("should apply custom style", () => {
+    const customStyle = { border: "2px solid blue", margin: "15px" };
+
+    const { container } = render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard style={customStyle} />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = container.querySelector('[style*="position: relative"]');
+    expect(board).toHaveStyle({ border: "2px solid blue" });
+    expect(board).toHaveStyle({ margin: "15px" });
+  });
+
+  it("should apply custom id", () => {
+    const { container } = render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard id="custom-puzzle-board-id" />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = container.querySelector('[style*="position: relative"]');
+    expect(board).toHaveAttribute("id", "custom-puzzle-board-id");
+  });
+
+  it("should apply data-* attributes", () => {
+    render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard data-testid="puzzle-board" data-custom="puzzle-value" />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = screen.getByTestId("puzzle-board");
+    expect(board).toHaveAttribute("data-custom", "puzzle-value");
+  });
+
+  it("should apply aria-* attributes", () => {
+    const { container } = render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard aria-label="Puzzle board" aria-describedby="puzzle-desc" />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = container.querySelector('[style*="position: relative"]');
+    expect(board).toHaveAttribute("aria-label", "Puzzle board");
+    expect(board).toHaveAttribute("aria-describedby", "puzzle-desc");
+  });
+
+  it("should accept custom onClick handler", () => {
+    const handleClick = jest.fn();
+
+    const { container } = render(
+      <ChessPuzzle.Root puzzle={mockPuzzle}>
+        <PuzzleBoard onClick={handleClick} />
+      </ChessPuzzle.Root>,
+    );
+
+    const board = container.querySelector(
+      '[style*="position: relative"]',
+    ) as HTMLElement;
+    board?.click();
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("should throw error when used outside ChessPuzzle.Root", () => {
+    // Suppress console.error for this test
+    const consoleError = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() => {
+      render(
+        <ChessGame.Root>
+          <PuzzleBoard />
+        </ChessGame.Root>,
+      );
+    }).toThrow(
+      "useChessPuzzleContext must be used within a ChessPuzzle component",
+    );
+
+    consoleError.mockRestore();
+  });
+});