@react-chess-tools/react-chess-game 0.5.2 → 1.0.0

package/src/docs/Theming.mdx

@@ -0,0 +1,281 @@
+{/* Theming.mdx */}
+import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';
+
+<Meta title="react-chess-game/Theming" />
+
+# Theming
+
+React Chess Tools provides a comprehensive theming system that allows you to customize the look and feel of your chess boards. You can customize board colors, move highlights, check indicators, and more.
+
+## Quick Start
+
+The simplest way to use a theme is to pass it to the `theme` prop on `ChessGame.Root`:
+
+```tsx
+import { ChessGame, themes } from "@react-chess-tools/react-chess-game";
+
+function App() {
+  return (
+    <ChessGame.Root theme={themes.lichess}>
+      <ChessGame.Board />
+    </ChessGame.Root>
+  );
+}
+```
+
+## Available Preset Themes
+
+We provide three built-in themes:
+
+<table>
+  <thead>
+    <tr>
+      <th>Theme</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>themes.default</code>
+      </td>
+      <td>Classic brown/beige board with yellow highlights</td>
+    </tr>
+    <tr>
+      <td>
+        <code>themes.lichess</code>
+      </td>
+      <td>Lichess.org inspired with green highlights</td>
+    </tr>
+    <tr>
+      <td>
+        <code>themes.chessCom</code>
+      </td>
+      <td>Chess.com inspired with green board and yellow highlights</td>
+    </tr>
+  </tbody>
+</table>
+
+```tsx
+import { themes } from "@react-chess-tools/react-chess-game";
+
+// Use a preset theme
+<ChessGame.Root theme={themes.lichess}>
+  <ChessGame.Board />
+</ChessGame.Root>;
+```
+
+## Theme Structure
+
+A complete theme has the following structure:
+
+```typescript
+interface ChessGameTheme {
+  board: {
+    lightSquare: CSSProperties; // Style for light squares
+    darkSquare: CSSProperties; // Style for dark squares
+  };
+  state: {
+    lastMove: string; // Color for last move highlight (RGBA)
+    check: string; // Color for check highlight (RGBA)
+    activeSquare: string; // Color for selected piece (RGBA)
+    dropSquare: CSSProperties; // Style for valid drop target
+  };
+  indicators: {
+    move: string; // Color for move dot indicators (RGBA)
+    capture: string; // Color for capture ring indicators (RGBA)
+  };
+}
+```
+
+## Creating a Custom Theme
+
+You can create a fully custom theme by defining all properties:
+
+```tsx
+import { ChessGame } from "@react-chess-tools/react-chess-game";
+import type { ChessGameTheme } from "@react-chess-tools/react-chess-game";
+
+const darkTheme: ChessGameTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#4a4a4a" },
+    darkSquare: { backgroundColor: "#2d2d2d" },
+  },
+  state: {
+    lastMove: "rgba(100, 150, 255, 0.5)",
+    check: "rgba(255, 50, 50, 0.6)",
+    activeSquare: "rgba(100, 150, 255, 0.5)",
+    dropSquare: { backgroundColor: "rgba(100, 150, 255, 0.3)" },
+  },
+  indicators: {
+    move: "rgba(200, 200, 200, 0.2)",
+    capture: "rgba(255, 100, 100, 0.3)",
+  },
+};
+
+function App() {
+  return (
+    <ChessGame.Root theme={darkTheme}>
+      <ChessGame.Board />
+    </ChessGame.Root>
+  );
+}
+```
+
+## Partial Theme Overrides
+
+You don't need to specify all theme properties. You can override only the colors you want to change, and the rest will use the default values:
+
+```tsx
+import { ChessGame } from "@react-chess-tools/react-chess-game";
+import type { PartialChessGameTheme } from "@react-chess-tools/react-chess-game";
+
+// Only override specific colors
+const customTheme: PartialChessGameTheme = {
+  state: {
+    lastMove: "rgba(147, 112, 219, 0.5)", // Purple
+    check: "rgba(255, 165, 0, 0.6)", // Orange
+  },
+};
+
+function App() {
+  return (
+    <ChessGame.Root theme={customTheme}>
+      <ChessGame.Board />
+    </ChessGame.Root>
+  );
+}
+```
+
+## Theme Utilities
+
+### mergeTheme
+
+Use `mergeTheme` to merge a partial theme with the default theme:
+
+```tsx
+import {
+  mergeTheme,
+  defaultGameTheme,
+} from "@react-chess-tools/react-chess-game";
+
+const myTheme = mergeTheme({
+  state: { lastMove: "rgba(0, 255, 0, 0.5)" },
+});
+// myTheme is now a complete ChessGameTheme with only lastMove changed
+```
+
+### mergeThemeWith
+
+Use `mergeThemeWith` to extend any base theme:
+
+```tsx
+import {
+  mergeThemeWith,
+  lichessTheme,
+} from "@react-chess-tools/react-chess-game";
+
+const customLichess = mergeThemeWith(lichessTheme, {
+  board: {
+    lightSquare: { backgroundColor: "#e8e8e8" },
+  },
+});
+```
+
+## Using the Theme Hook
+
+For advanced use cases, you can access the current theme from any component inside `ChessGame.Root`:
+
+```tsx
+import { useChessGameTheme } from "@react-chess-tools/react-chess-game";
+
+function CustomComponent() {
+  const theme = useChessGameTheme();
+
+  return (
+    <div style={{ backgroundColor: theme.state.lastMove }}>
+      Current last move color: {theme.state.lastMove}
+    </div>
+  );
+}
+```
+
+## Runtime Theme Switching
+
+Themes can be switched at runtime by updating the `theme` prop:
+
+```tsx
+import { useState } from "react";
+import { ChessGame, themes } from "@react-chess-tools/react-chess-game";
+
+function App() {
+  const [currentTheme, setCurrentTheme] = useState(themes.default);
+
+  return (
+    <div>
+      <ChessGame.Root theme={currentTheme}>
+        <ChessGame.Board />
+      </ChessGame.Root>
+
+      <div>
+        <button onClick={() => setCurrentTheme(themes.default)}>Default</button>
+        <button onClick={() => setCurrentTheme(themes.lichess)}>Lichess</button>
+        <button onClick={() => setCurrentTheme(themes.chessCom)}>
+          Chess.com
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Default Theme Colors
+
+<ColorPalette>
+  <ColorItem
+    title="Board Colors"
+    subtitle="Light and dark squares"
+    colors={{
+      "Light Square": "#f0d9b5",
+      "Dark Square": "#b58863",
+    }}
+  />
+  <ColorItem
+    title="State Colors"
+    subtitle="Game state highlights"
+    colors={{
+      "Last Move": "rgba(255, 255, 0, 0.5)",
+      Check: "rgba(255, 0, 0, 0.5)",
+      "Active Square": "rgba(255, 255, 0, 0.5)",
+      "Drop Target": "rgba(255, 255, 0, 0.4)",
+    }}
+  />
+  <ColorItem
+    title="Indicator Colors"
+    subtitle="Move and capture indicators"
+    colors={{
+      "Move Dot": "rgba(0, 0, 0, 0.1)",
+      "Capture Ring": "rgba(1, 0, 0, 0.1)",
+    }}
+  />
+</ColorPalette>
+
+## TypeScript Support
+
+All theme types are fully exported for TypeScript users:
+
+```typescript
+import type {
+  ChessGameTheme,
+  PartialChessGameTheme,
+  BoardTheme,
+  StateTheme,
+  IndicatorTheme,
+} from "@react-chess-tools/react-chess-game";
+```
+
+## Next Steps
+
+- Try the **[Theme Playground](/story/react-chess-game-theme-playground--playground)** to experiment with colors interactively
+- See **[Theme Presets](/story/react-chess-game-theme-presets--all-presets)** for visual comparison of built-in themes
+- Check out **[Puzzle Theming](/docs/react-chess-puzzle-theming--docs)** for puzzle-specific theme options

package/src/hooks/useChessGame.ts

@@ -11,10 +11,22 @@ export const useChessGame = ({
   fen,
   orientation: initialOrientation,
 }: useChessGameProps = {}) => {
-  const [game, setGame] = React.useState(new Chess(fen));
+  const [game, setGame] = React.useState(() => {
+    try {
+      return new Chess(fen);
+    } catch (e) {
+      console.error("Invalid FEN:", fen, e);
+      return new Chess(); // Return empty board
+    }
+  });
 
   useEffect(() => {
-    setGame(new Chess(fen));
+    try {
+      setGame(new Chess(fen));
+    } catch (e) {
+      console.error("Invalid FEN:", fen, e);
+      setGame(new Chess());
+    }
   }, [fen]);
 
   const [orientation, setOrientation] = React.useState<Color>(
@@ -44,11 +56,15 @@ export const useChessGame = ({
   );
 
   const setPosition = React.useCallback((fen: string, orientation: Color) => {
-    const newGame = new Chess();
-    newGame.load(fen);
-    setOrientation(orientation);
-    setGame(newGame);
-    setCurrentMoveIndex(-1);
+    try {
+      const newGame = new Chess();
+      newGame.load(fen);
+      setOrientation(orientation);
+      setGame(newGame);
+      setCurrentMoveIndex(-1);
+    } catch (e) {
+      console.error("Failed to load FEN:", fen, e);
+    }
   }, []);
 
   const makeMove = React.useCallback(

package/src/index.ts

@@ -21,3 +21,22 @@ export { deepMergeChessboardOptions } from "./utils/board";
 // Component Props
 export type { ChessGameProps } from "./components/ChessGame/parts/Board";
 export type { RootProps } from "./components/ChessGame/parts/Root";
+
+// Theme - Types
+export type {
+  ChessGameTheme,
+  BoardTheme,
+  StateTheme,
+  IndicatorTheme,
+  PartialChessGameTheme,
+  DeepPartial,
+} from "./theme/types";
+
+// Theme - Values
+export { defaultGameTheme } from "./theme/defaults";
+export { lichessTheme, chessComTheme } from "./theme/presets";
+export { themes } from "./theme";
+
+// Theme - Utilities
+export { mergeTheme, mergeThemeWith } from "./theme/utils";
+export { useChessGameTheme, ChessGameThemeContext } from "./theme/context";

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

@@ -0,0 +1,75 @@
+import React from "react";
+import { renderHook } from "@testing-library/react";
+import { useChessGameTheme, ThemeProvider } from "../context";
+import { defaultGameTheme } from "../defaults";
+import { lichessTheme } from "../presets";
+
+describe("useChessGameTheme", () => {
+  it("should return default theme when no provider is present", () => {
+    const { result } = renderHook(() => useChessGameTheme());
+    expect(result.current).toEqual(defaultGameTheme);
+  });
+
+  it("should return provided theme when wrapped in ThemeProvider", () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ThemeProvider theme={lichessTheme}>{children}</ThemeProvider>
+    );
+
+    const { result } = renderHook(() => useChessGameTheme(), { wrapper });
+    expect(result.current).toEqual(lichessTheme);
+  });
+
+  it("should return custom theme with all properties", () => {
+    const customTheme = {
+      ...defaultGameTheme,
+      state: {
+        ...defaultGameTheme.state,
+        lastMove: "rgba(100, 200, 100, 0.6)",
+      },
+    };
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ThemeProvider theme={customTheme}>{children}</ThemeProvider>
+    );
+
+    const { result } = renderHook(() => useChessGameTheme(), { wrapper });
+    expect(result.current.state.lastMove).toBe("rgba(100, 200, 100, 0.6)");
+  });
+});
+
+describe("ThemeProvider", () => {
+  it("should render children", () => {
+    const TestComponent = () => {
+      const theme = useChessGameTheme();
+      return <div data-testid="theme-check">{theme.state.lastMove}</div>;
+    };
+
+    const { result } = renderHook(() => useChessGameTheme(), {
+      wrapper: ({ children }) => (
+        <ThemeProvider theme={defaultGameTheme}>{children}</ThemeProvider>
+      ),
+    });
+
+    expect(result.current).toBeTruthy();
+  });
+
+  it("should allow nested providers with inner provider winning", () => {
+    const outerTheme = {
+      ...defaultGameTheme,
+      state: { ...defaultGameTheme.state, lastMove: "outer" },
+    };
+    const innerTheme = {
+      ...defaultGameTheme,
+      state: { ...defaultGameTheme.state, lastMove: "inner" },
+    };
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ThemeProvider theme={outerTheme}>
+        <ThemeProvider theme={innerTheme}>{children}</ThemeProvider>
+      </ThemeProvider>
+    );
+
+    const { result } = renderHook(() => useChessGameTheme(), { wrapper });
+    expect(result.current.state.lastMove).toBe("inner");
+  });
+});

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

@@ -0,0 +1,61 @@
+import { defaultGameTheme } from "../defaults";
+
+describe("defaultGameTheme", () => {
+  describe("backward compatibility", () => {
+    it("should have the original lastMove color", () => {
+      expect(defaultGameTheme.state.lastMove).toBe("rgba(255, 255, 0, 0.5)");
+    });
+
+    it("should have the original check color", () => {
+      expect(defaultGameTheme.state.check).toBe("rgba(255, 0, 0, 0.5)");
+    });
+
+    it("should have the original activeSquare color", () => {
+      expect(defaultGameTheme.state.activeSquare).toBe(
+        "rgba(255, 255, 0, 0.5)",
+      );
+    });
+
+    it("should have the original dropSquare style", () => {
+      expect(defaultGameTheme.state.dropSquare).toEqual({
+        backgroundColor: "rgba(255, 255, 0, 0.4)",
+      });
+    });
+
+    it("should have the original move indicator color", () => {
+      expect(defaultGameTheme.indicators.move).toBe("rgba(0, 0, 0, 0.1)");
+    });
+
+    it("should have the original capture indicator color", () => {
+      expect(defaultGameTheme.indicators.capture).toBe("rgba(1, 0, 0, 0.1)");
+    });
+  });
+
+  describe("structure", () => {
+    it("should have board property with lightSquare and darkSquare", () => {
+      expect(defaultGameTheme.board).toHaveProperty("lightSquare");
+      expect(defaultGameTheme.board).toHaveProperty("darkSquare");
+    });
+
+    it("should have state property with all required colors", () => {
+      expect(defaultGameTheme.state).toHaveProperty("lastMove");
+      expect(defaultGameTheme.state).toHaveProperty("check");
+      expect(defaultGameTheme.state).toHaveProperty("activeSquare");
+      expect(defaultGameTheme.state).toHaveProperty("dropSquare");
+    });
+
+    it("should have indicators property with move and capture", () => {
+      expect(defaultGameTheme.indicators).toHaveProperty("move");
+      expect(defaultGameTheme.indicators).toHaveProperty("capture");
+    });
+
+    it("should have valid CSS properties for board squares", () => {
+      expect(defaultGameTheme.board.lightSquare).toHaveProperty(
+        "backgroundColor",
+      );
+      expect(defaultGameTheme.board.darkSquare).toHaveProperty(
+        "backgroundColor",
+      );
+    });
+  });
+});

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

@@ -0,0 +1,106 @@
+import { mergeTheme, mergeThemeWith } from "../utils";
+import { defaultGameTheme } from "../defaults";
+import { lichessTheme } from "../presets";
+
+describe("mergeTheme", () => {
+  it("should return default theme when no partial theme is provided", () => {
+    const result = mergeTheme();
+    expect(result).toEqual(defaultGameTheme);
+  });
+
+  it("should return default theme when undefined is provided", () => {
+    const result = mergeTheme(undefined);
+    expect(result).toEqual(defaultGameTheme);
+  });
+
+  it("should return a new object, not a reference to default", () => {
+    const result = mergeTheme();
+    expect(result).not.toBe(defaultGameTheme);
+  });
+
+  it("should override a single nested property", () => {
+    const result = mergeTheme({
+      state: { lastMove: "rgba(100, 200, 100, 0.6)" },
+    });
+
+    expect(result.state.lastMove).toBe("rgba(100, 200, 100, 0.6)");
+    // Other state properties should remain default
+    expect(result.state.check).toBe(defaultGameTheme.state.check);
+    expect(result.state.activeSquare).toBe(defaultGameTheme.state.activeSquare);
+    expect(result.state.dropSquare).toEqual(defaultGameTheme.state.dropSquare);
+  });
+
+  it("should override multiple properties in different groups", () => {
+    const result = mergeTheme({
+      state: { lastMove: "rgba(100, 200, 100, 0.6)" },
+      board: { lightSquare: { backgroundColor: "#eeeeee" } },
+    });
+
+    expect(result.state.lastMove).toBe("rgba(100, 200, 100, 0.6)");
+    expect(result.board.lightSquare).toEqual({ backgroundColor: "#eeeeee" });
+    // Dark square should remain default
+    expect(result.board.darkSquare).toEqual(defaultGameTheme.board.darkSquare);
+  });
+
+  it("should override indicator colors", () => {
+    const result = mergeTheme({
+      indicators: {
+        move: "rgba(50, 50, 50, 0.2)",
+        capture: "rgba(200, 50, 50, 0.3)",
+      },
+    });
+
+    expect(result.indicators.move).toBe("rgba(50, 50, 50, 0.2)");
+    expect(result.indicators.capture).toBe("rgba(200, 50, 50, 0.3)");
+  });
+
+  it("should override dropSquare style completely", () => {
+    const result = mergeTheme({
+      state: {
+        dropSquare: {
+          backgroundColor: "rgba(0, 255, 0, 0.5)",
+          border: "2px solid green",
+        },
+      },
+    });
+
+    expect(result.state.dropSquare).toEqual({
+      backgroundColor: "rgba(0, 255, 0, 0.5)",
+      border: "2px solid green",
+    });
+  });
+
+  it("should preserve unmentioned theme properties", () => {
+    const result = mergeTheme({
+      state: { check: "rgba(255, 100, 100, 0.8)" },
+    });
+
+    expect(result.board).toEqual(defaultGameTheme.board);
+    expect(result.indicators).toEqual(defaultGameTheme.indicators);
+  });
+});
+
+describe("mergeThemeWith", () => {
+  it("should merge partial theme with provided base theme", () => {
+    const result = mergeThemeWith(lichessTheme, {
+      state: { check: "rgba(255, 0, 0, 0.9)" },
+    });
+
+    // Check should be overridden
+    expect(result.state.check).toBe("rgba(255, 0, 0, 0.9)");
+    // Other lichess theme values should be preserved
+    expect(result.state.lastMove).toBe(lichessTheme.state.lastMove);
+    expect(result.board).toEqual(lichessTheme.board);
+  });
+
+  it("should return copy of base theme when no partial is provided", () => {
+    const result = mergeThemeWith(lichessTheme);
+    expect(result).toEqual(lichessTheme);
+    expect(result).not.toBe(lichessTheme);
+  });
+
+  it("should return copy of base theme when undefined partial is provided", () => {
+    const result = mergeThemeWith(lichessTheme, undefined);
+    expect(result).toEqual(lichessTheme);
+  });
+});

package/src/theme/context.tsx

@@ -0,0 +1,37 @@
+import React, { createContext, useContext } from "react";
+import type { ChessGameTheme } from "./types";
+import { defaultGameTheme } from "./defaults";
+
+/**
+ * Context for ChessGame theme
+ */
+export const ChessGameThemeContext =
+  createContext<ChessGameTheme>(defaultGameTheme);
+
+/**
+ * Hook to access the current ChessGame theme.
+ * Returns the default theme if no ThemeProvider is present.
+ */
+export const useChessGameTheme = (): ChessGameTheme => {
+  return useContext(ChessGameThemeContext);
+};
+
+export interface ThemeProviderProps {
+  theme: ChessGameTheme;
+  children: React.ReactNode;
+}
+
+/**
+ * Internal provider component used by Root when a theme prop is provided.
+ * This is not exported directly - users pass theme via Root's theme prop.
+ */
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({
+  theme,
+  children,
+}) => {
+  return (
+    <ChessGameThemeContext.Provider value={theme}>
+      {children}
+    </ChessGameThemeContext.Provider>
+  );
+};

package/src/theme/defaults.ts

@@ -0,0 +1,22 @@
+import type { ChessGameTheme } from "./types";
+
+/**
+ * Default theme for ChessGame component.
+ * These values match the original hardcoded colors for backward compatibility.
+ */
+export const defaultGameTheme: ChessGameTheme = {
+  board: {
+    lightSquare: { backgroundColor: "#f0d9b5" },
+    darkSquare: { backgroundColor: "#b58863" },
+  },
+  state: {
+    lastMove: "rgba(255, 255, 0, 0.5)",
+    check: "rgba(255, 0, 0, 0.5)",
+    activeSquare: "rgba(255, 255, 0, 0.5)",
+    dropSquare: { backgroundColor: "rgba(255, 255, 0, 0.4)" },
+  },
+  indicators: {
+    move: "rgba(0, 0, 0, 0.1)",
+    capture: "rgba(1, 0, 0, 0.1)",
+  },
+};

package/src/theme/index.ts

@@ -0,0 +1,36 @@
+// Types
+export type {
+  ChessGameTheme,
+  BoardTheme,
+  StateTheme,
+  IndicatorTheme,
+  PartialChessGameTheme,
+  DeepPartial,
+} from "./types";
+
+// Default theme
+export { defaultGameTheme } from "./defaults";
+
+// Preset themes
+export { lichessTheme, chessComTheme } from "./presets";
+
+// All themes as a single object
+import { defaultGameTheme } from "./defaults";
+import { lichessTheme, chessComTheme } from "./presets";
+
+export const themes = {
+  default: defaultGameTheme,
+  lichess: lichessTheme,
+  chessCom: chessComTheme,
+} as const;
+
+// Utilities
+export { mergeTheme, mergeThemeWith } from "./utils";
+
+// Context and hook
+export {
+  ChessGameThemeContext,
+  useChessGameTheme,
+  ThemeProvider,
+} from "./context";
+export type { ThemeProviderProps } from "./context";