@react-chess-tools/react-chess-game 0.4.2 → 0.5.1

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

@@ -1,5 +1,5 @@
 import { Chess } from "chess.js";
-import { getCustomSquareStyles } from "../board";
+import { getCustomSquareStyles, deepMergeChessboardOptions } from "../board";
 import { getGameInfo } from "../chess";
 
 describe("Board Utilities", () => {
@@ -140,4 +140,259 @@ describe("Board Utilities", () => {
       expect(styles.c3.background).toContain("25%");
     });
   });
+
+  describe("deepMergeChessboardOptions", () => {
+    it("should deeply merge nested object options without overriding computed values", () => {
+      const baseOptions = {
+        squareStyles: {
+          e4: {
+            backgroundColor: "rgba(255, 255, 0, 0.5)", // Computed move highlighting
+            background:
+              "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)", // Move dot
+          },
+        },
+        dropSquareStyle: {
+          backgroundColor: "rgba(255, 255, 0, 0.4)",
+          border: "2px dashed yellow",
+        },
+        showNotation: true,
+        allowDrawingArrows: true,
+      };
+
+      const customOptions = {
+        squareStyles: {
+          e4: {
+            border: "2px solid red", // Should be added without removing background
+          },
+          a1: {
+            backgroundColor: "blue", // New square style
+          },
+        },
+        dropSquareStyle: {
+          backgroundColor: "rgba(0, 255, 0, 0.6)", // Should override backgroundColor but preserve border
+        },
+        showNotation: false, // Should override primitive
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, customOptions);
+
+      // squareStyles should deep merge
+      expect(result.squareStyles?.e4).toEqual({
+        backgroundColor: "rgba(255, 255, 0, 0.5)",
+        background:
+          "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)",
+        border: "2px solid red",
+      });
+      expect(result.squareStyles?.a1).toEqual({
+        backgroundColor: "blue",
+      });
+
+      // dropSquareStyle should deep merge
+      expect(result.dropSquareStyle).toEqual({
+        backgroundColor: "rgba(0, 255, 0, 0.6)",
+        border: "2px dashed yellow",
+      });
+
+      // Primitives should override
+      expect(result.showNotation).toBe(false);
+      expect(result.allowDrawingArrows).toBe(true);
+    });
+
+    it("should handle function properties by overwriting them", () => {
+      const baseOnSquareClick = jest.fn();
+      const baseCanDragPiece = jest.fn();
+      const customOnSquareClick = jest.fn();
+
+      const baseOptions = {
+        onSquareClick: baseOnSquareClick,
+        canDragPiece: baseCanDragPiece,
+        showNotation: true,
+      };
+
+      const customOptions = {
+        onSquareClick: customOnSquareClick,
+        // canDragPiece not provided - should keep base function
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, customOptions);
+
+      // Custom function should replace base function
+      expect(result.onSquareClick).toBe(customOnSquareClick);
+      expect(result.onSquareClick).not.toBe(baseOnSquareClick);
+
+      // Base function should be preserved when not overridden
+      expect(result.canDragPiece).toBe(baseCanDragPiece);
+
+      // Other properties should merge normally
+      expect(result.showNotation).toBe(true);
+    });
+
+    it("should handle nested object properties by deep merging them", () => {
+      const baseOptions = {
+        darkSquareStyle: {
+          backgroundColor: "#8B4513",
+        },
+      };
+
+      const customOptions = {
+        darkSquareStyle: {
+          backgroundColor: "#654321",
+          border: "1px solid black",
+        },
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, customOptions);
+
+      expect(result.darkSquareStyle).toEqual({
+        backgroundColor: "#654321",
+        border: "1px solid black",
+      });
+    });
+
+    it("should handle undefined custom options gracefully", () => {
+      const baseOptions = {
+        squareStyles: {
+          e4: { backgroundColor: "yellow" },
+        },
+        showNotation: true,
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, undefined);
+
+      expect(result).toEqual(baseOptions);
+      expect(result).not.toBe(baseOptions); // Should be a new object
+    });
+
+    it("should handle empty custom options", () => {
+      const baseOptions = {
+        squareStyles: {
+          e4: { backgroundColor: "yellow" },
+        },
+        showNotation: true,
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, {});
+
+      expect(result).toEqual(baseOptions);
+      expect(result).not.toBe(baseOptions); // Should be a new object
+    });
+
+    it("should preserve complex nested object structures", () => {
+      const baseOptions = {
+        squareStyles: {
+          e4: {
+            backgroundColor: "rgba(255, 255, 0, 0.5)",
+            background:
+              "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)",
+            border: "1px solid black",
+          },
+          d5: {
+            backgroundColor: "rgba(0, 255, 0, 0.3)",
+          },
+        },
+      };
+
+      const customOptions = {
+        squareStyles: {
+          e4: {
+            borderRadius: "4px", // Add new property
+            backgroundColor: "rgba(255, 0, 0, 0.5)", // Override existing
+            // background should be preserved from base
+          },
+          f6: {
+            backgroundColor: "blue", // New square
+          },
+        },
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, customOptions);
+
+      expect(result.squareStyles?.e4).toEqual({
+        backgroundColor: "rgba(255, 0, 0, 0.5)", // Overridden
+        background:
+          "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)", // Preserved
+        border: "1px solid black", // Preserved
+        borderRadius: "4px", // Added
+      });
+
+      expect(result.squareStyles?.d5).toEqual({
+        backgroundColor: "rgba(0, 255, 0, 0.3)", // Preserved from base
+      });
+
+      expect(result.squareStyles?.f6).toEqual({
+        backgroundColor: "blue", // Added from custom
+      });
+    });
+
+    it("should handle real-world Board component use case", () => {
+      // Simulate the actual use case in Board component
+      const computedSquareStyles = {
+        e2: {
+          backgroundColor: "rgba(255, 255, 0, 0.5)", // Active square highlight
+        },
+        e3: {
+          background:
+            "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)", // Move dot
+        },
+        e4: {
+          background:
+            "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)", // Move dot
+        },
+      };
+
+      const baseOptions = {
+        squareStyles: computedSquareStyles,
+        boardOrientation: "white" as const,
+        position: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+        showNotation: true,
+        onSquareClick: jest.fn(),
+      };
+
+      const userCustomOptions = {
+        squareStyles: {
+          e4: {
+            border: "2px solid red", // User wants to add border to a square that has move dots
+          },
+          a1: {
+            backgroundColor: "lightblue", // User wants to highlight corner square
+          },
+        },
+        showNotation: false, // User wants to hide notation
+        onSquareClick: jest.fn(), // User provides custom click handler
+      };
+
+      const result = deepMergeChessboardOptions(baseOptions, userCustomOptions);
+
+      // Move highlighting should be preserved while adding user's border
+      expect(result.squareStyles?.e4).toEqual({
+        background:
+          "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)",
+        border: "2px solid red",
+      });
+
+      // User's new square style should be added
+      expect(result.squareStyles?.a1).toEqual({
+        backgroundColor: "lightblue",
+      });
+
+      // Other computed styles should be preserved
+      expect(result.squareStyles?.e2).toEqual({
+        backgroundColor: "rgba(255, 255, 0, 0.5)",
+      });
+      expect(result.squareStyles?.e3).toEqual({
+        background:
+          "radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)",
+      });
+
+      // Primitives should be overridden
+      expect(result.showNotation).toBe(false);
+      expect(result.position).toBe(
+        "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+      );
+
+      // Functions should be replaced
+      expect(result.onSquareClick).toBe(userCustomOptions.onSquareClick);
+      expect(result.onSquareClick).not.toBe(baseOptions.onSquareClick);
+    });
+  });
 });

package/src/utils/board.ts

@@ -1,5 +1,7 @@
 import { type Chess, type Square } from "chess.js";
 import { type CSSProperties } from "react";
+import { merge } from "lodash";
+import type { ChessboardOptions } from "react-chessboard";
 import { getDestinationSquares, type GameInfo } from "./chess";
 
 const LAST_MOVE_COLOR = "rgba(255, 255, 0, 0.5)";
@@ -54,3 +56,50 @@ export const getCustomSquareStyles = (
   }
   return customSquareStyles;
 };
+
+/**
+ * Smart deep merge for ChessboardOptions that handles different property types appropriately:
+ * - Functions: Overwrite (custom functions replace base functions)
+ * - Objects: Deep merge (nested objects merge recursively)
+ * - Primitives: Overwrite (custom values replace base values)
+ *
+ * This ensures that computed options (like squareStyles with move highlighting) are preserved
+ * while allowing custom options to extend or override them intelligently.
+ *
+ * @param baseOptions - The computed base options (e.g., computed squareStyles, event handlers)
+ * @param customOptions - Custom options provided by the user
+ * @returns Intelligently merged ChessboardOptions
+ */
+export const deepMergeChessboardOptions = (
+  baseOptions: ChessboardOptions,
+  customOptions?: Partial<ChessboardOptions>,
+): ChessboardOptions => {
+  if (!customOptions) {
+    return { ...baseOptions }; // Return a new object even when no custom options
+  }
+
+  const result = merge({}, baseOptions, customOptions, {
+    customizer: (_objValue: unknown, srcValue: unknown) => {
+      // Functions should always overwrite (not merge)
+      // This is important for event handlers like onSquareClick, onPieceDrop, etc.
+      if (typeof srcValue === "function") {
+        return srcValue;
+      }
+
+      // For arrays, we typically want to overwrite rather than merge
+      // This avoids unexpected behavior with array concatenation
+      if (Array.isArray(srcValue)) {
+        return srcValue;
+      }
+
+      // Let lodash handle objects with default deep merge behavior
+      // This will properly merge nested objects like squareStyles, dropSquareStyle, etc.
+      return undefined; // Use default merge behavior
+    },
+  });
+
+  // Clean up any unwanted properties that lodash might add
+  delete (result as Record<string, unknown>).customizer;
+
+  return result;
+};