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

package/src/docs/Theming.mdx

@@ -0,0 +1,255 @@
+{/* Theming.mdx */}
+import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';
+
+<Meta title="react-chess-puzzle/Theming" />
+
+# Puzzle Theming
+
+React Chess Puzzle extends the game theming system with puzzle-specific colors for hints, success, and failure states.
+
+## Quick Start
+
+Pass a theme to `ChessPuzzle.Root` to customize puzzle appearance:
+
+```tsx
+import { ChessPuzzle } from "@react-chess-tools/react-chess-puzzle";
+
+const puzzle = {
+  fen: "4kb1r/p2r1ppp/4qn2/1B2p1B1/4P3/1Q6/PPP2PPP/2KR4 w k - 0 1",
+  moves: ["Bxd7+", "Nxd7", "Qb8+", "Nxb8", "Rd8#"],
+};
+
+function App() {
+  return (
+    <ChessPuzzle.Root
+      puzzle={puzzle}
+      theme={{ puzzle: { hint: "rgba(255, 215, 0, 0.6)" } }}
+    >
+      <ChessPuzzle.Board />
+      <ChessPuzzle.Hint>Show Hint</ChessPuzzle.Hint>
+    </ChessPuzzle.Root>
+  );
+}
+```
+
+## Puzzle Theme Structure
+
+The puzzle theme extends `ChessGameTheme` with an additional `puzzle` section:
+
+```typescript
+interface ChessPuzzleTheme extends ChessGameTheme {
+  puzzle: {
+    success: string; // Color for correct moves (RGBA)
+    failure: string; // Color for incorrect moves (RGBA)
+    hint: string; // Color for hint squares (RGBA)
+  };
+}
+```
+
+## Puzzle-Specific Colors
+
+The puzzle theme adds three new color options:
+
+<table>
+  <thead>
+    <tr>
+      <th>Color</th>
+      <th>Usage</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>puzzle.success</code>
+      </td>
+      <td>Highlights squares when a correct move is made</td>
+    </tr>
+    <tr>
+      <td>
+        <code>puzzle.failure</code>
+      </td>
+      <td>Highlights squares when an incorrect move is made</td>
+    </tr>
+    <tr>
+      <td>
+        <code>puzzle.hint</code>
+      </td>
+      <td>Highlights the hint square(s) when hint is requested</td>
+    </tr>
+  </tbody>
+</table>
+
+## Creating a Custom Puzzle Theme
+
+You can customize both game and puzzle colors:
+
+```tsx
+import { ChessPuzzle } from "@react-chess-tools/react-chess-puzzle";
+import type { PartialChessPuzzleTheme } from "@react-chess-tools/react-chess-puzzle";
+
+const neonTheme: PartialChessPuzzleTheme = {
+  // Customize board colors (inherited from game theme)
+  board: {
+    lightSquare: { backgroundColor: "#2a2a2a" },
+    darkSquare: { backgroundColor: "#1a1a1a" },
+  },
+  // Customize game state colors
+  state: {
+    lastMove: "rgba(0, 255, 255, 0.4)",
+  },
+  // Customize puzzle-specific colors
+  puzzle: {
+    success: "rgba(0, 255, 127, 0.6)",
+    failure: "rgba(255, 0, 127, 0.6)",
+    hint: "rgba(0, 191, 255, 0.6)",
+  },
+};
+
+function App() {
+  return (
+    <ChessPuzzle.Root puzzle={puzzle} theme={neonTheme}>
+      <ChessPuzzle.Board />
+    </ChessPuzzle.Root>
+  );
+}
+```
+
+## Partial Theme Overrides
+
+Override only the puzzle colors you need:
+
+```tsx
+// Only change the hint color to gold
+const goldHint: PartialChessPuzzleTheme = {
+  puzzle: {
+    hint: "rgba(255, 215, 0, 0.6)",
+  },
+};
+
+// Only change success/failure colors
+const customFeedback: PartialChessPuzzleTheme = {
+  puzzle: {
+    success: "rgba(0, 200, 100, 0.7)",
+    failure: "rgba(200, 0, 50, 0.7)",
+  },
+};
+```
+
+## Theme Inheritance
+
+Puzzle themes inherit all game theme properties. You can:
+
+1. **Only specify puzzle colors** - game colors use defaults
+2. **Only specify game colors** - puzzle colors use defaults
+3. **Mix both** - customize any combination
+
+```tsx
+// Example: Custom board + default puzzle colors
+const customBoard: PartialChessPuzzleTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#e8e8e8" },
+    darkSquare: { backgroundColor: "#4a4a4a" },
+  },
+};
+
+// Example: Default board + custom puzzle colors
+const customPuzzle: PartialChessPuzzleTheme = {
+  puzzle: {
+    success: "rgba(100, 255, 100, 0.5)",
+    failure: "rgba(255, 100, 100, 0.5)",
+    hint: "rgba(100, 100, 255, 0.5)",
+  },
+};
+```
+
+## Using Theme Utilities
+
+### mergePuzzleTheme
+
+Merge a partial puzzle theme with defaults:
+
+```tsx
+import {
+  mergePuzzleTheme,
+  defaultPuzzleTheme,
+} from "@react-chess-tools/react-chess-puzzle";
+
+const myTheme = mergePuzzleTheme({
+  puzzle: { hint: "rgba(255, 215, 0, 0.6)" },
+});
+// myTheme is now a complete ChessPuzzleTheme
+```
+
+### useChessPuzzleTheme Hook
+
+Access the current puzzle theme from any component:
+
+```tsx
+import { useChessPuzzleTheme } from "@react-chess-tools/react-chess-puzzle";
+
+function HintButton() {
+  const theme = useChessPuzzleTheme();
+
+  return (
+    <button style={{ backgroundColor: theme.puzzle.hint }}>Show Hint</button>
+  );
+}
+```
+
+## Default Puzzle Colors
+
+<ColorPalette>
+  <ColorItem
+    title="Puzzle Colors"
+    subtitle="Puzzle state feedback"
+    colors={{
+      Success: "rgba(172, 206, 89, 0.5)",
+      Failure: "rgba(201, 52, 48, 0.5)",
+      Hint: "rgba(27, 172, 166, 0.5)",
+    }}
+  />
+</ColorPalette>
+
+## Example Theme Variations
+
+### Pastel Theme
+
+```tsx
+const pastelTheme: PartialChessPuzzleTheme = {
+  puzzle: {
+    success: "rgba(152, 251, 152, 0.6)", // Pale green
+    failure: "rgba(255, 182, 193, 0.6)", // Light pink
+    hint: "rgba(173, 216, 230, 0.6)", // Light blue
+  },
+};
+```
+
+### High Contrast Theme
+
+```tsx
+const highContrastTheme: PartialChessPuzzleTheme = {
+  puzzle: {
+    success: "rgba(0, 255, 0, 0.7)",
+    failure: "rgba(255, 0, 0, 0.7)",
+    hint: "rgba(0, 255, 255, 0.7)",
+  },
+};
+```
+
+## TypeScript Support
+
+All puzzle theme types are exported:
+
+```typescript
+import type {
+  ChessPuzzleTheme,
+  PartialChessPuzzleTheme,
+  PuzzleStateTheme,
+} from "@react-chess-tools/react-chess-puzzle";
+```
+
+## Next Steps
+
+- Try the **[Puzzle Theme Playground](/story/react-chess-puzzle-theme-playground--puzzle-playground)** to experiment with colors
+- See **[Puzzle Theme Examples](/story/react-chess-puzzle-theme-playground--puzzle-theme-examples)** for inspiration
+- Check out **[Game Theming](/docs/react-chess-game-theming--docs)** for board and state color options

package/src/index.ts

@@ -13,3 +13,17 @@ export type { HintProps } from "./components/ChessPuzzle/parts/Hint";
 export type { ResetProps } from "./components/ChessPuzzle/parts/Reset";
 export type { PuzzleBoardProps } from "./components/ChessPuzzle/parts/PuzzleBoard";
 export type { RootProps } from "./components/ChessPuzzle/parts/Root";
+
+// Theme - Types
+export type {
+  ChessPuzzleTheme,
+  PuzzleStateTheme,
+  PartialChessPuzzleTheme,
+} from "./theme/types";
+
+// Theme - Values
+export { defaultPuzzleTheme } from "./theme/defaults";
+
+// Theme - Utilities
+export { mergePuzzleTheme } from "./theme/utils";
+export { useChessPuzzleTheme, ChessPuzzleThemeContext } from "./theme/context";

package/src/theme/__tests__/context.test.tsx

@@ -0,0 +1,66 @@
+import React from "react";
+import { renderHook } from "@testing-library/react";
+import { useChessPuzzleTheme, PuzzleThemeProvider } from "../context";
+import { defaultPuzzleTheme } from "../defaults";
+
+describe("useChessPuzzleTheme", () => {
+  it("should return default puzzle theme when no provider is present", () => {
+    const { result } = renderHook(() => useChessPuzzleTheme());
+    expect(result.current).toEqual(defaultPuzzleTheme);
+  });
+
+  it("should return provided theme when wrapped in PuzzleThemeProvider", () => {
+    const customTheme = {
+      ...defaultPuzzleTheme,
+      puzzle: {
+        ...defaultPuzzleTheme.puzzle,
+        hint: "rgba(0, 255, 255, 0.5)",
+      },
+    };
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PuzzleThemeProvider theme={customTheme}>{children}</PuzzleThemeProvider>
+    );
+
+    const { result } = renderHook(() => useChessPuzzleTheme(), { wrapper });
+    expect(result.current.puzzle.hint).toBe("rgba(0, 255, 255, 0.5)");
+  });
+
+  it("should return all puzzle-specific properties", () => {
+    const { result } = renderHook(() => useChessPuzzleTheme());
+
+    expect(result.current.puzzle).toHaveProperty("success");
+    expect(result.current.puzzle).toHaveProperty("failure");
+    expect(result.current.puzzle).toHaveProperty("hint");
+  });
+
+  it("should return inherited game theme properties", () => {
+    const { result } = renderHook(() => useChessPuzzleTheme());
+
+    expect(result.current.board).toBeDefined();
+    expect(result.current.state).toBeDefined();
+    expect(result.current.indicators).toBeDefined();
+  });
+});
+
+describe("PuzzleThemeProvider", () => {
+  it("should allow nested providers with inner provider winning", () => {
+    const outerTheme = {
+      ...defaultPuzzleTheme,
+      puzzle: { ...defaultPuzzleTheme.puzzle, hint: "outer" },
+    };
+    const innerTheme = {
+      ...defaultPuzzleTheme,
+      puzzle: { ...defaultPuzzleTheme.puzzle, hint: "inner" },
+    };
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PuzzleThemeProvider theme={outerTheme}>
+        <PuzzleThemeProvider theme={innerTheme}>{children}</PuzzleThemeProvider>
+      </PuzzleThemeProvider>
+    );
+
+    const { result } = renderHook(() => useChessPuzzleTheme(), { wrapper });
+    expect(result.current.puzzle.hint).toBe("inner");
+  });
+});

package/src/theme/__tests__/defaults.test.ts

@@ -0,0 +1,48 @@
+import { defaultPuzzleTheme } from "../defaults";
+import { defaultGameTheme } from "@react-chess-tools/react-chess-game";
+
+describe("defaultPuzzleTheme", () => {
+  describe("backward compatibility", () => {
+    it("should have the original success color", () => {
+      expect(defaultPuzzleTheme.puzzle.success).toBe("rgba(172, 206, 89, 0.5)");
+    });
+
+    it("should have the original failure color", () => {
+      expect(defaultPuzzleTheme.puzzle.failure).toBe("rgba(201, 52, 48, 0.5)");
+    });
+
+    it("should have the original hint color", () => {
+      expect(defaultPuzzleTheme.puzzle.hint).toBe("rgba(27, 172, 166, 0.5)");
+    });
+  });
+
+  describe("inheritance from game theme", () => {
+    it("should include all game theme properties", () => {
+      expect(defaultPuzzleTheme.board).toBeDefined();
+      expect(defaultPuzzleTheme.state).toBeDefined();
+      expect(defaultPuzzleTheme.indicators).toBeDefined();
+    });
+
+    it("should have the same board colors as game theme", () => {
+      expect(defaultPuzzleTheme.board).toEqual(defaultGameTheme.board);
+    });
+
+    it("should have the same state colors as game theme", () => {
+      expect(defaultPuzzleTheme.state).toEqual(defaultGameTheme.state);
+    });
+
+    it("should have the same indicator colors as game theme", () => {
+      expect(defaultPuzzleTheme.indicators).toEqual(
+        defaultGameTheme.indicators,
+      );
+    });
+  });
+
+  describe("structure", () => {
+    it("should have puzzle property with all required colors", () => {
+      expect(defaultPuzzleTheme.puzzle).toHaveProperty("success");
+      expect(defaultPuzzleTheme.puzzle).toHaveProperty("failure");
+      expect(defaultPuzzleTheme.puzzle).toHaveProperty("hint");
+    });
+  });
+});

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

@@ -0,0 +1,76 @@
+import { mergePuzzleTheme } from "../utils";
+import { defaultPuzzleTheme } from "../defaults";
+
+describe("mergePuzzleTheme", () => {
+  it("should return default puzzle theme when no partial theme is provided", () => {
+    const result = mergePuzzleTheme();
+    expect(result).toEqual(defaultPuzzleTheme);
+  });
+
+  it("should return default puzzle theme when undefined is provided", () => {
+    const result = mergePuzzleTheme(undefined);
+    expect(result).toEqual(defaultPuzzleTheme);
+  });
+
+  it("should return a new object, not a reference to default", () => {
+    const result = mergePuzzleTheme();
+    expect(result).not.toBe(defaultPuzzleTheme);
+  });
+
+  it("should override puzzle-specific colors", () => {
+    const result = mergePuzzleTheme({
+      puzzle: { hint: "rgba(0, 255, 255, 0.5)" },
+    });
+
+    expect(result.puzzle.hint).toBe("rgba(0, 255, 255, 0.5)");
+    // Other puzzle colors should remain default
+    expect(result.puzzle.success).toBe(defaultPuzzleTheme.puzzle.success);
+    expect(result.puzzle.failure).toBe(defaultPuzzleTheme.puzzle.failure);
+  });
+
+  it("should override all puzzle colors at once", () => {
+    const result = mergePuzzleTheme({
+      puzzle: {
+        success: "rgba(0, 255, 0, 0.5)",
+        failure: "rgba(255, 0, 0, 0.5)",
+        hint: "rgba(0, 0, 255, 0.5)",
+      },
+    });
+
+    expect(result.puzzle.success).toBe("rgba(0, 255, 0, 0.5)");
+    expect(result.puzzle.failure).toBe("rgba(255, 0, 0, 0.5)");
+    expect(result.puzzle.hint).toBe("rgba(0, 0, 255, 0.5)");
+  });
+
+  it("should override inherited game theme properties", () => {
+    const result = mergePuzzleTheme({
+      state: { lastMove: "rgba(100, 200, 100, 0.6)" },
+      board: { lightSquare: { backgroundColor: "#ffffff" } },
+    });
+
+    expect(result.state.lastMove).toBe("rgba(100, 200, 100, 0.6)");
+    expect(result.board.lightSquare).toEqual({ backgroundColor: "#ffffff" });
+    // Puzzle colors should remain default
+    expect(result.puzzle).toEqual(defaultPuzzleTheme.puzzle);
+  });
+
+  it("should allow overriding both game and puzzle properties", () => {
+    const result = mergePuzzleTheme({
+      state: { check: "rgba(255, 100, 100, 0.8)" },
+      puzzle: { success: "rgba(100, 255, 100, 0.8)" },
+    });
+
+    expect(result.state.check).toBe("rgba(255, 100, 100, 0.8)");
+    expect(result.puzzle.success).toBe("rgba(100, 255, 100, 0.8)");
+  });
+
+  it("should preserve unmentioned theme properties", () => {
+    const result = mergePuzzleTheme({
+      puzzle: { hint: "rgba(0, 255, 255, 0.5)" },
+    });
+
+    expect(result.board).toEqual(defaultPuzzleTheme.board);
+    expect(result.state).toEqual(defaultPuzzleTheme.state);
+    expect(result.indicators).toEqual(defaultPuzzleTheme.indicators);
+  });
+});

package/src/theme/context.tsx

@@ -0,0 +1,36 @@
+import React, { createContext, useContext } from "react";
+import type { ChessPuzzleTheme } from "./types";
+import { defaultPuzzleTheme } from "./defaults";
+
+/**
+ * Context for ChessPuzzle theme
+ */
+export const ChessPuzzleThemeContext =
+  createContext<ChessPuzzleTheme>(defaultPuzzleTheme);
+
+/**
+ * Hook to access the current ChessPuzzle theme.
+ * Returns the default puzzle theme if no ThemeProvider is present.
+ */
+export const useChessPuzzleTheme = (): ChessPuzzleTheme => {
+  return useContext(ChessPuzzleThemeContext);
+};
+
+export interface PuzzleThemeProviderProps {
+  theme: ChessPuzzleTheme;
+  children: React.ReactNode;
+}
+
+/**
+ * Internal provider component used by Puzzle Root when a theme prop is provided.
+ */
+export const PuzzleThemeProvider: React.FC<PuzzleThemeProviderProps> = ({
+  theme,
+  children,
+}) => {
+  return (
+    <ChessPuzzleThemeContext.Provider value={theme}>
+      {children}
+    </ChessPuzzleThemeContext.Provider>
+  );
+};

package/src/theme/defaults.ts

@@ -0,0 +1,16 @@
+import { defaultGameTheme } from "@react-chess-tools/react-chess-game";
+import type { ChessPuzzleTheme } from "./types";
+
+/**
+ * Default theme for ChessPuzzle component.
+ * Extends the default game theme with puzzle-specific colors.
+ * These values match the original hardcoded colors for backward compatibility.
+ */
+export const defaultPuzzleTheme: ChessPuzzleTheme = {
+  ...defaultGameTheme,
+  puzzle: {
+    success: "rgba(172, 206, 89, 0.5)",
+    failure: "rgba(201, 52, 48, 0.5)",
+    hint: "rgba(27, 172, 166, 0.5)",
+  },
+};

package/src/theme/index.ts

@@ -0,0 +1,20 @@
+// Types
+export type {
+  ChessPuzzleTheme,
+  PuzzleStateTheme,
+  PartialChessPuzzleTheme,
+} from "./types";
+
+// Default theme
+export { defaultPuzzleTheme } from "./defaults";
+
+// Utilities
+export { mergePuzzleTheme } from "./utils";
+
+// Context and hook
+export {
+  ChessPuzzleThemeContext,
+  useChessPuzzleTheme,
+  PuzzleThemeProvider,
+} from "./context";
+export type { PuzzleThemeProviderProps } from "./context";

package/src/theme/types.ts

@@ -0,0 +1,29 @@
+import type {
+  ChessGameTheme,
+  DeepPartial,
+} from "@react-chess-tools/react-chess-game";
+
+/**
+ * Puzzle-specific state colors (RGBA color strings)
+ */
+export interface PuzzleStateTheme {
+  /** Background color for successful moves */
+  success: string;
+  /** Background color for failed moves */
+  failure: string;
+  /** Background color for hint squares */
+  hint: string;
+}
+
+/**
+ * Complete theme configuration for ChessPuzzle component.
+ * Extends ChessGameTheme with puzzle-specific colors.
+ */
+export interface ChessPuzzleTheme extends ChessGameTheme {
+  puzzle: PuzzleStateTheme;
+}
+
+/**
+ * Partial theme for puzzle customization - allows overriding only specific properties
+ */
+export type PartialChessPuzzleTheme = DeepPartial<ChessPuzzleTheme>;

package/src/theme/utils.ts

@@ -0,0 +1,28 @@
+import { merge } from "lodash";
+import type { ChessPuzzleTheme, PartialChessPuzzleTheme } from "./types";
+import { defaultPuzzleTheme } from "./defaults";
+
+/**
+ * Deep merges a partial puzzle theme with the default puzzle theme.
+ * Allows users to override only specific theme properties while keeping defaults for the rest.
+ *
+ * @param partialTheme - Partial theme with only the properties to override
+ * @returns Complete puzzle theme with overridden properties merged with defaults
+ *
+ * @example
+ * ```typescript
+ * const customTheme = mergePuzzleTheme({
+ *   puzzle: { hint: "rgba(0, 255, 255, 0.5)" }
+ * });
+ * // Returns full puzzle theme with only hint color changed
+ * ```
+ */
+export const mergePuzzleTheme = (
+  partialTheme?: PartialChessPuzzleTheme,
+): ChessPuzzleTheme => {
+  if (!partialTheme) {
+    return { ...defaultPuzzleTheme };
+  }
+
+  return merge({}, defaultPuzzleTheme, partialTheme);
+};

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