@react-chess-tools/react-chess-puzzle 1.0.1 → 1.0.3

package/src/components/ChessPuzzle/ChessPuzzle.stories.tsx

@@ -18,6 +18,105 @@ const puzzles = [
   },
 ];
 
+// ============================================================================
+// Shared Story Styles
+// ============================================================================
+const storyStyles = {
+  container: {
+    display: "flex",
+    flexDirection: "column" as const,
+    alignItems: "center",
+    gap: "20px",
+    padding: "24px",
+    backgroundColor: "#f8f9fa",
+    borderRadius: "12px",
+    maxWidth: "500px",
+    margin: "0 auto",
+  },
+  header: {
+    display: "flex",
+    flexDirection: "column" as const,
+    alignItems: "center",
+    gap: "8px",
+  },
+  title: {
+    fontSize: "22px",
+    fontWeight: 700,
+    color: "#2c3e50",
+    margin: 0,
+    textAlign: "center" as const,
+  },
+  subtitle: {
+    fontSize: "14px",
+    color: "#6c757d",
+    margin: 0,
+    textAlign: "center" as const,
+  },
+  boardWrapper: {
+    backgroundColor: "#fff",
+    padding: "16px",
+    borderRadius: "10px",
+    boxShadow: "0 2px 12px rgba(0,0,0,0.08)",
+  },
+  controlsSection: {
+    display: "flex",
+    gap: "10px",
+    justifyContent: "center",
+    flexWrap: "wrap" as const,
+  },
+  button: {
+    padding: "10px 20px",
+    fontSize: "14px",
+    fontWeight: 600,
+    cursor: "pointer",
+    border: "none",
+    borderRadius: "8px",
+    backgroundColor: "#fff",
+    boxShadow: "0 2px 6px rgba(0,0,0,0.08)",
+    color: "#495057",
+    transition: "all 0.2s ease",
+  } as React.CSSProperties,
+  buttonPrimary: {
+    backgroundColor: "#4dabf7",
+    color: "#fff",
+    boxShadow: "0 2px 6px rgba(77, 171, 247, 0.3)",
+  } as React.CSSProperties,
+  buttonSuccess: {
+    backgroundColor: "#51cf66",
+    color: "#fff",
+    boxShadow: "0 2px 6px rgba(81, 207, 102, 0.3)",
+  } as React.CSSProperties,
+  hintButton: {
+    padding: "8px 16px",
+    fontSize: "13px",
+    fontWeight: 500,
+    cursor: "pointer",
+    border: "1px dashed #adb5bd",
+    borderRadius: "8px",
+    backgroundColor: "transparent",
+    color: "#868e96",
+  } as React.CSSProperties,
+  infoBox: {
+    padding: "12px 16px",
+    backgroundColor: "#e7f5ff",
+    borderRadius: "8px",
+    fontSize: "13px",
+    color: "#1864ab",
+    textAlign: "center" as const,
+  },
+  statusBadge: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "6px",
+    padding: "6px 14px",
+    fontSize: "12px",
+    fontWeight: 600,
+    backgroundColor: "#e9ecef",
+    borderRadius: "20px",
+    color: "#495057",
+  },
+};
+
 // More on how to set up stories at: https://storybook.js.org/docs/react/writing-stories/introduction
 const meta = {
   title: "react-chess-puzzle/Components/Puzzle",
@@ -29,15 +128,8 @@ const meta = {
   },
   parameters: {
     actions: { argTypesRegex: "^_on.*" },
+    layout: "centered",
   },
-  decorators: [
-    (Story) => (
-      <div style={{ width: "400px" }}>
-        {/* 👇 Decorators in Storybook also accept a function. Replace <Story/> with Story() to enable it  */}
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof ChessPuzzle.Root>;
 
 export default meta;
@@ -48,49 +140,70 @@ export const Example = (args: RootProps) => {
   const [puzzleIndex, setPuzzleIndex] = React.useState(0);
   const puzzle = puzzles[puzzleIndex];
   return (
-    <div>
-      <ChessPuzzle.Root {...args} puzzle={puzzle}>
-        <ChessPuzzle.Board />
-        <ChessPuzzle.Reset asChild>
-          <button>restart</button>
-        </ChessPuzzle.Reset>
-        <ChessPuzzle.Reset
-          asChild
-          puzzle={puzzles[(puzzleIndex + 1) % puzzles.length]}
-          onReset={() => setPuzzleIndex((puzzleIndex + 1) % puzzles.length)}
-        >
-          <button>next</button>
-        </ChessPuzzle.Reset>
-        <ChessPuzzle.Hint>hint</ChessPuzzle.Hint>
-      </ChessPuzzle.Root>
-    </div>
+    <ChessPuzzle.Root {...args} puzzle={puzzle}>
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Chess Puzzle</h3>
+          <p style={storyStyles.subtitle}>Find the best move sequence</p>
+          <span style={storyStyles.statusBadge}>
+            Puzzle {puzzleIndex + 1} of {puzzles.length}
+          </span>
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <div style={storyStyles.controlsSection}>
+          <ChessPuzzle.Reset asChild>
+            <button style={storyStyles.button}>Restart</button>
+          </ChessPuzzle.Reset>
+          <ChessPuzzle.Reset
+            asChild
+            puzzle={puzzles[(puzzleIndex + 1) % puzzles.length]}
+            onReset={() => setPuzzleIndex((puzzleIndex + 1) % puzzles.length)}
+          >
+            <button
+              style={{ ...storyStyles.button, ...storyStyles.buttonPrimary }}
+            >
+              Next Puzzle
+            </button>
+          </ChessPuzzle.Reset>
+          <ChessPuzzle.Hint style={storyStyles.hintButton}>
+            💡 Hint
+          </ChessPuzzle.Hint>
+        </div>
+      </div>
+    </ChessPuzzle.Root>
   );
 };
 
 export const WithOrientation = (args: RootProps) => {
-  const [puzzleIndex, setPuzzleIndex] = React.useState(0);
   const puzzle = {
     fen: "4kbnr/2p1pp1p/pp4p1/5b2/8/2NB1N2/PP3PPP/RKB4R b k - 0 1",
     makeFirstMove: false,
     moves: ["Bxd3"],
   };
   return (
-    <div>
-      <ChessPuzzle.Root {...args} puzzle={puzzle}>
-        <ChessPuzzle.Board options={{ boardOrientation: "black" }} />
-        <ChessPuzzle.Reset asChild>
-          <button>restart</button>
-        </ChessPuzzle.Reset>
-        <ChessPuzzle.Reset
-          asChild
-          puzzle={puzzle}
-          onReset={() => setPuzzleIndex((puzzleIndex + 1) % puzzles.length)}
-        >
-          <button>next</button>
-        </ChessPuzzle.Reset>
-        <ChessPuzzle.Hint>hint</ChessPuzzle.Hint>
-      </ChessPuzzle.Root>
-    </div>
+    <ChessPuzzle.Root {...args} puzzle={puzzle}>
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Black to Move</h3>
+          <p style={storyStyles.subtitle}>
+            Board oriented from Black's perspective
+          </p>
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board options={{ boardOrientation: "black" }} />
+        </div>
+        <div style={storyStyles.controlsSection}>
+          <ChessPuzzle.Reset asChild>
+            <button style={storyStyles.button}>Restart</button>
+          </ChessPuzzle.Reset>
+          <ChessPuzzle.Hint style={storyStyles.hintButton}>
+            💡 Hint
+          </ChessPuzzle.Hint>
+        </div>
+      </div>
+    </ChessPuzzle.Root>
   );
 };
 
@@ -101,14 +214,31 @@ export const Underpromotion = (args: RootProps) => {
     makeFirstMove: true,
   };
   return (
-    <div>
-      <ChessPuzzle.Root {...args} puzzle={puzzle}>
-        <ChessPuzzle.Board />
-        <ChessPuzzle.Reset asChild>
-          <button>done! Restart</button>
-        </ChessPuzzle.Reset>
-      </ChessPuzzle.Root>
-    </div>
+    <ChessPuzzle.Root {...args} puzzle={puzzle}>
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Underpromotion Challenge</h3>
+          <p style={storyStyles.subtitle}>
+            Promote to a knight instead of a queen
+          </p>
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <div style={storyStyles.controlsSection}>
+          <ChessPuzzle.Reset asChild>
+            <button
+              style={{ ...storyStyles.button, ...storyStyles.buttonSuccess }}
+            >
+              ✓ Solved! Restart
+            </button>
+          </ChessPuzzle.Reset>
+        </div>
+        <div style={storyStyles.infoBox}>
+          Sometimes promoting to a knight is better than a queen!
+        </div>
+      </div>
+    </ChessPuzzle.Root>
   );
 };
 
@@ -116,7 +246,18 @@ export const WithSounds = (args: RootProps) => {
   return (
     <ChessPuzzle.Root {...args} puzzle={puzzles[0]}>
       <ChessGame.Sounds />
-      <ChessPuzzle.Board />
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Puzzle with Sound</h3>
+          <p style={storyStyles.subtitle}>Audio feedback on every move</p>
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <p style={{ fontSize: "12px", color: "#868e96", textAlign: "center" }}>
+          Move pieces to hear different sounds
+        </p>
+      </div>
     </ChessPuzzle.Root>
   );
 };
@@ -133,7 +274,224 @@ export const WithKeyboardControls = (args: RootProps) => {
           d: (context) => context.methods.goToNextMove(),
         }}
       />
-      <ChessPuzzle.Board />
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Keyboard Navigation</h3>
+          <p style={storyStyles.subtitle}>Use keyboard shortcuts to navigate</p>
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(3, auto)",
+            gap: "8px",
+            justifyContent: "center",
+            marginTop: "12px",
+          }}
+        >
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "6px",
+              fontSize: "12px",
+              color: "#495057",
+            }}
+          >
+            <kbd
+              style={{
+                padding: "2px 8px",
+                backgroundColor: "#e9ecef",
+                border: "1px solid #ced4da",
+                borderRadius: "4px",
+                fontFamily: "monospace",
+                fontSize: "11px",
+                fontWeight: 600,
+              }}
+            >
+              W
+            </kbd>{" "}
+            Start
+          </div>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "6px",
+              fontSize: "12px",
+              color: "#495057",
+            }}
+          >
+            <kbd
+              style={{
+                padding: "2px 8px",
+                backgroundColor: "#e9ecef",
+                border: "1px solid #ced4da",
+                borderRadius: "4px",
+                fontFamily: "monospace",
+                fontSize: "11px",
+                fontWeight: 600,
+              }}
+            >
+              A
+            </kbd>{" "}
+            Previous
+          </div>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "6px",
+              fontSize: "12px",
+              color: "#495057",
+            }}
+          >
+            <kbd
+              style={{
+                padding: "2px 8px",
+                backgroundColor: "#e9ecef",
+                border: "1px solid #ced4da",
+                borderRadius: "4px",
+                fontFamily: "monospace",
+                fontSize: "11px",
+                fontWeight: 600,
+              }}
+            >
+              F
+            </kbd>{" "}
+            Flip
+          </div>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "6px",
+              fontSize: "12px",
+              color: "#495057",
+            }}
+          >
+            <kbd
+              style={{
+                padding: "2px 8px",
+                backgroundColor: "#e9ecef",
+                border: "1px solid #ced4da",
+                borderRadius: "4px",
+                fontFamily: "monospace",
+                fontSize: "11px",
+                fontWeight: 600,
+              }}
+            >
+              S
+            </kbd>{" "}
+            End
+          </div>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "6px",
+              fontSize: "12px",
+              color: "#495057",
+            }}
+          >
+            <kbd
+              style={{
+                padding: "2px 8px",
+                backgroundColor: "#e9ecef",
+                border: "1px solid #ced4da",
+                borderRadius: "4px",
+                fontFamily: "monospace",
+                fontSize: "11px",
+                fontWeight: 600,
+              }}
+            >
+              D
+            </kbd>{" "}
+            Next
+          </div>
+        </div>
+      </div>
+    </ChessPuzzle.Root>
+  );
+};
+
+// Puzzle with multiple checkmate solutions for testing solveOnCheckmate prop
+const multiMatePuzzle = {
+  fen: "7k/R7/1R6/2Q5/4Q3/8/8/7K w - - 0 1",
+  moves: ["a7a8"], // Canonical solution
+  makeFirstMove: false,
+};
+
+export const MultiMatePuzzle = (args: RootProps) => {
+  return (
+    <ChessPuzzle.Root {...args} puzzle={multiMatePuzzle}>
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Flexible Checkmate</h3>
+          <p style={storyStyles.subtitle}>
+            Any checkmate move solves the puzzle
+          </p>
+        </div>
+        <div
+          style={{
+            ...storyStyles.infoBox,
+            backgroundColor: "#d3f9d8",
+            color: "#2b8a3e",
+          }}
+        >
+          <strong>solveOnCheckmate=true (default)</strong>
+          <br />
+          Try Qc8#, Qf8#, Rb8#, or the canonical Ra8#
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <div style={storyStyles.controlsSection}>
+          <ChessPuzzle.Reset asChild>
+            <button style={storyStyles.button}>Restart</button>
+          </ChessPuzzle.Reset>
+        </div>
+      </div>
+    </ChessPuzzle.Root>
+  );
+};
+
+export const MultiMatePuzzleStrict = (args: RootProps) => {
+  return (
+    <ChessPuzzle.Root
+      {...args}
+      puzzle={multiMatePuzzle}
+      solveOnCheckmate={false}
+    >
+      <div style={storyStyles.container}>
+        <div style={storyStyles.header}>
+          <h3 style={storyStyles.title}>Strict Checkmate</h3>
+          <p style={storyStyles.subtitle}>
+            Only the canonical solution is accepted
+          </p>
+        </div>
+        <div
+          style={{
+            ...storyStyles.infoBox,
+            backgroundColor: "#ffe3e3",
+            color: "#c92a2a",
+          }}
+        >
+          <strong>solveOnCheckmate=false</strong>
+          <br />
+          Only Ra8# is accepted. Alternative mates like Qc8# will fail!
+        </div>
+        <div style={storyStyles.boardWrapper}>
+          <ChessPuzzle.Board />
+        </div>
+        <div style={storyStyles.controlsSection}>
+          <ChessPuzzle.Reset asChild>
+            <button style={storyStyles.button}>Restart</button>
+          </ChessPuzzle.Reset>
+        </div>
+      </div>
     </ChessPuzzle.Root>
   );
 };

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,7 +62,12 @@ 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>

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");
+    });
+  });
 });