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

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

@@ -0,0 +1,300 @@
+import type { Meta } from "@storybook/react";
+import React, { useState } from "react";
+import { ChessPuzzle } from "./index";
+import { defaultPuzzleTheme } from "../../theme/defaults";
+import type { ChessPuzzleTheme } from "../../theme/types";
+
+const meta = {
+  title: "react-chess-puzzle/Theme/Playground",
+  component: ChessPuzzle.Root,
+  tags: ["theme", "puzzle"],
+  decorators: [
+    (Story) => (
+      <div style={{ maxWidth: "900px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof ChessPuzzle.Root>;
+
+export default meta;
+
+const samplePuzzle = {
+  fen: "4kb1r/p2r1ppp/4qn2/1B2p1B1/4P3/1Q6/PPP2PPP/2KR4 w k - 0 1",
+  moves: ["Bxd7+", "Nxd7", "Qb8+", "Nxb8", "Rd8#"],
+  makeFirstMove: false,
+};
+
+// Color picker component
+const ColorInput: React.FC<{
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+}> = ({ label, value, onChange }) => {
+  const rgbaToHex = (rgba: string): string => {
+    const match = rgba.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+    if (match) {
+      const r = parseInt(match[1]).toString(16).padStart(2, "0");
+      const g = parseInt(match[2]).toString(16).padStart(2, "0");
+      const b = parseInt(match[3]).toString(16).padStart(2, "0");
+      return `#${r}${g}${b}`;
+    }
+    return value.startsWith("#") ? value : "#000000";
+  };
+
+  const hexToRgba = (hex: string, alpha: number = 0.5): string => {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: "8px",
+        marginBottom: "8px",
+      }}
+    >
+      <input
+        type="color"
+        value={rgbaToHex(value)}
+        onChange={(e) => onChange(hexToRgba(e.target.value))}
+        style={{ width: "40px", height: "30px", cursor: "pointer" }}
+      />
+      <span style={{ fontSize: "12px", minWidth: "100px" }}>{label}</span>
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        style={{ fontSize: "11px", width: "180px", padding: "4px" }}
+      />
+    </div>
+  );
+};
+
+export const PuzzlePlayground = () => {
+  const [theme, setTheme] = useState<ChessPuzzleTheme>(defaultPuzzleTheme);
+  const [copied, setCopied] = useState(false);
+  const [puzzleKey, setPuzzleKey] = useState(0);
+
+  const updatePuzzleColor = (
+    key: keyof ChessPuzzleTheme["puzzle"],
+    value: string,
+  ) => {
+    setTheme((prev) => ({
+      ...prev,
+      puzzle: {
+        ...prev.puzzle,
+        [key]: value,
+      },
+    }));
+  };
+
+  const copyTheme = () => {
+    const themeCode = `const myPuzzleTheme: PartialChessPuzzleTheme = {
+  puzzle: ${JSON.stringify(theme.puzzle, null, 4)}
+};`;
+    navigator.clipboard.writeText(themeCode);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  const resetPuzzle = () => {
+    setPuzzleKey((k) => k + 1);
+  };
+
+  return (
+    <div style={{ display: "flex", gap: "24px", flexWrap: "wrap" }}>
+      <div style={{ flex: "1", minWidth: "300px" }}>
+        <h3 style={{ marginBottom: "16px" }}>Puzzle Theme Editor</h3>
+
+        <div style={{ marginBottom: "16px" }}>
+          <strong>Puzzle Colors</strong>
+          <div style={{ marginTop: "8px" }}>
+            <ColorInput
+              label="Success"
+              value={theme.puzzle.success}
+              onChange={(v) => updatePuzzleColor("success", v)}
+            />
+            <ColorInput
+              label="Failure"
+              value={theme.puzzle.failure}
+              onChange={(v) => updatePuzzleColor("failure", v)}
+            />
+            <ColorInput
+              label="Hint"
+              value={theme.puzzle.hint}
+              onChange={(v) => updatePuzzleColor("hint", v)}
+            />
+          </div>
+        </div>
+
+        <div style={{ display: "flex", gap: "8px", marginBottom: "16px" }}>
+          <button
+            onClick={copyTheme}
+            style={{
+              padding: "8px 16px",
+              backgroundColor: copied ? "#4caf50" : "#2196f3",
+              color: "white",
+              border: "none",
+              borderRadius: "4px",
+              cursor: "pointer",
+            }}
+          >
+            {copied ? "Copied!" : "Copy Theme Code"}
+          </button>
+          <button
+            onClick={resetPuzzle}
+            style={{
+              padding: "8px 16px",
+              backgroundColor: "#666",
+              color: "white",
+              border: "none",
+              borderRadius: "4px",
+              cursor: "pointer",
+            }}
+          >
+            Reset Puzzle
+          </button>
+        </div>
+
+        <div style={{ fontSize: "12px", color: "#666" }}>
+          <p>
+            <strong>How to test colors:</strong>
+          </p>
+          <ul style={{ paddingLeft: "16px" }}>
+            <li>Click "Hint" to see the hint color</li>
+            <li>Make a correct move to see success color</li>
+            <li>Make a wrong move to see failure color</li>
+            <li>Click "Reset" to try again</li>
+          </ul>
+        </div>
+      </div>
+
+      <div style={{ flex: "1", minWidth: "350px" }}>
+        <h3 style={{ marginBottom: "16px" }}>Preview</h3>
+        <div style={{ maxWidth: "400px" }}>
+          <ChessPuzzle.Root key={puzzleKey} puzzle={samplePuzzle} theme={theme}>
+            <ChessPuzzle.Board />
+            <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+              <ChessPuzzle.Hint asChild>
+                <button style={{ padding: "6px 12px" }}>Hint</button>
+              </ChessPuzzle.Hint>
+              <ChessPuzzle.Reset asChild>
+                <button style={{ padding: "6px 12px" }}>Reset</button>
+              </ChessPuzzle.Reset>
+            </div>
+          </ChessPuzzle.Root>
+        </div>
+        <p style={{ fontSize: "12px", color: "#666", marginTop: "8px" }}>
+          Solution: Bxd7+, Nxd7, Qb8+, Nxb8, Rd8#
+        </p>
+      </div>
+    </div>
+  );
+};
+
+export const PuzzleThemeExamples = () => {
+  const customThemes = {
+    default: defaultPuzzleTheme,
+    neon: {
+      ...defaultPuzzleTheme,
+      puzzle: {
+        success: "rgba(0, 255, 127, 0.6)",
+        failure: "rgba(255, 0, 127, 0.6)",
+        hint: "rgba(0, 191, 255, 0.6)",
+      },
+    },
+    pastel: {
+      ...defaultPuzzleTheme,
+      puzzle: {
+        success: "rgba(152, 251, 152, 0.6)",
+        failure: "rgba(255, 182, 193, 0.6)",
+        hint: "rgba(173, 216, 230, 0.6)",
+      },
+    },
+  };
+
+  return (
+    <div>
+      <h2 style={{ marginBottom: "24px" }}>Puzzle Theme Examples</h2>
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(auto-fit, minmax(300px, 1fr))",
+          gap: "24px",
+        }}
+      >
+        {Object.entries(customThemes).map(([name, theme]) => (
+          <div key={name}>
+            <h4 style={{ marginBottom: "8px", textTransform: "capitalize" }}>
+              {name}
+            </h4>
+            <ChessPuzzle.Root puzzle={samplePuzzle} theme={theme}>
+              <ChessPuzzle.Board />
+              <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+                <ChessPuzzle.Hint asChild>
+                  <button style={{ padding: "4px 8px", fontSize: "12px" }}>
+                    Hint
+                  </button>
+                </ChessPuzzle.Hint>
+                <ChessPuzzle.Reset asChild>
+                  <button style={{ padding: "4px 8px", fontSize: "12px" }}>
+                    Reset
+                  </button>
+                </ChessPuzzle.Reset>
+              </div>
+            </ChessPuzzle.Root>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export const PartialPuzzleTheme = () => {
+  // Only override puzzle colors, inherit game colors from default
+  const partialTheme = {
+    puzzle: {
+      hint: "rgba(255, 215, 0, 0.6)", // Gold
+    },
+  };
+
+  return (
+    <div style={{ maxWidth: "500px" }}>
+      <h3>Partial Puzzle Theme</h3>
+      <p style={{ fontSize: "14px", color: "#666", marginBottom: "16px" }}>
+        Only override the hint color to gold. Success and failure use defaults.
+      </p>
+      <ChessPuzzle.Root puzzle={samplePuzzle} theme={partialTheme}>
+        <ChessPuzzle.Board />
+        <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+          <ChessPuzzle.Hint asChild>
+            <button style={{ padding: "6px 12px" }}>Show Gold Hint</button>
+          </ChessPuzzle.Hint>
+          <ChessPuzzle.Reset asChild>
+            <button style={{ padding: "6px 12px" }}>Reset</button>
+          </ChessPuzzle.Reset>
+        </div>
+      </ChessPuzzle.Root>
+      <details style={{ marginTop: "16px" }}>
+        <summary style={{ cursor: "pointer", fontSize: "14px" }}>
+          View theme code
+        </summary>
+        <pre
+          style={{
+            fontSize: "11px",
+            background: "#f5f5f5",
+            padding: "12px",
+            overflow: "auto",
+          }}
+        >
+          {JSON.stringify(partialTheme, null, 2)}
+        </pre>
+      </details>
+    </div>
+  );
+};

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

@@ -6,15 +6,19 @@ import {
 } from "@react-chess-tools/react-chess-game";
 import { getCustomSquareStyles, stringToMove } from "../../../utils";
 import { useChessPuzzleContext } from "../../..";
+import { useChessPuzzleTheme } from "../../../theme/context";
+
+export interface PuzzleBoardProps extends React.ComponentProps<
+  typeof ChessGame.Board
+> {}
 
-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();
 
   if (!puzzleContext) {
     throw new Error("PuzzleContext not found");
@@ -33,6 +37,7 @@ export const PuzzleBoard: React.FC<PuzzleBoardProps> = ({
       isPlayerTurn,
       game,
       stringToMove(game, nextMove),
+      theme,
     ),
   });
 

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

@@ -6,14 +6,26 @@ import {
 } from "../../../hooks/useChessPuzzle";
 import { ChessGame } from "@react-chess-tools/react-chess-game";
 import { ChessPuzzleContext } from "../../../hooks/useChessPuzzleContext";
+import { PuzzleThemeProvider } from "../../../theme/context";
+import { mergePuzzleTheme } from "../../../theme/utils";
+import type { PartialChessPuzzleTheme } from "../../../theme/types";
 
 export interface RootProps {
   puzzle: Puzzle;
   onSolve?: (puzzleContext: ChessPuzzleContextType) => void;
   onFail?: (puzzleContext: ChessPuzzleContextType) => void;
+  /** Optional theme configuration. Supports partial themes - only override the colors you need. */
+  theme?: PartialChessPuzzleTheme;
 }
 
-const PuzzleRoot: React.FC<React.PropsWithChildren<RootProps>> = ({
+interface PuzzleRootInnerProps {
+  puzzle: Puzzle;
+  onSolve?: (puzzleContext: ChessPuzzleContextType) => void;
+  onFail?: (puzzleContext: ChessPuzzleContextType) => void;
+  children: React.ReactNode;
+}
+
+const PuzzleRootInner: React.FC<PuzzleRootInnerProps> = ({
   puzzle,
   onSolve,
   onFail,
@@ -32,13 +44,23 @@ export const Root: React.FC<React.PropsWithChildren<RootProps>> = ({
   puzzle,
   onSolve,
   onFail,
+  theme,
   children,
 }) => {
+  // Merge partial theme with defaults
+  const mergedTheme = React.useMemo(() => mergePuzzleTheme(theme), [theme]);
+
   return (
-    <ChessGame.Root fen={puzzle.fen} orientation={getOrientation(puzzle)}>
-      <PuzzleRoot puzzle={puzzle} onSolve={onSolve} onFail={onFail}>
-        {children}
-      </PuzzleRoot>
+    <ChessGame.Root
+      fen={puzzle.fen}
+      orientation={getOrientation(puzzle)}
+      theme={mergedTheme}
+    >
+      <PuzzleThemeProvider theme={mergedTheme}>
+        <PuzzleRootInner puzzle={puzzle} onSolve={onSolve} onFail={onFail}>
+          {children}
+        </PuzzleRootInner>
+      </PuzzleThemeProvider>
     </ChessGame.Root>
   );
 };

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";