@mirasen/react-chessboard 1.0.2 → 1.1.0

package/README.md

@@ -14,9 +14,10 @@ Start with a working chessboard, not a board primitive.
 
 These examples use the same Mirasen chessboard runtime that powers the React component.
 
-- [Play a chess.js game](https://mirasen.io/chessboard/examples/chessjs.html)
-- [Try the promotion flow](https://mirasen.io/chessboard/examples/promotion.html)
-- [Try the minimal example](https://mirasen.io/chessboard/examples/minimal.html)
+- [Play a chess.js game](https://mirasen.io/chessboard/examples/chessjs)
+- [Watch 12 live boards](https://mirasen.io/chessboard/examples/live-games-grid)
+- [Try the promotion flow](https://mirasen.io/chessboard/examples/promotion)
+- [Try the minimal example](https://mirasen.io/chessboard/examples/minimal)
 
 ## Why this exists
 
@@ -33,6 +34,14 @@ Most React chessboard components give you a board primitive and leave the real c
 
 React owns lifecycle and props. Mirasen owns board rendering, input, interaction, animation, promotion, and extension behavior.
 
+## Real-world migration feedback
+
+After initially using `react-chessboard` and implementing click-to-move and move highlighting in application code, [TheUnemployedHobo](https://github.com/TheUnemployedHobo) explained why he migrated to Mirasen:
+
+> "But the code ended up getting so messy that I didn't even want to look at it anymore. It was painful to read. That's when I decided I needed a library that handled those things properly out of the box, and that's how I ended up switching to yours."
+
+— Author of [multiplayer-chess](https://github.com/TheUnemployedHobo/multiplayer-chess) · [Full discussion](https://github.com/TheUnemployedHobo/multiplayer-chess/issues/1#issuecomment-5356049391)
+
 ## Installation
 
 ```bash
@@ -236,7 +245,8 @@ import type {
 	MoveOutput,
 	MoveRequestInput,
 	MovabilityInput,
-	PositionInput
+	PositionInput,
+	SquareString
 } from '@mirasen/react-chessboard';
 
 type PositionRequest = {
@@ -256,6 +266,7 @@ type ChessboardProps = {
 	movability?: MovabilityInput;
 	onUIMove?: (move: MoveOutput) => void;
 	autoPromoteToQueen?: boolean;
+	checkSquare?: SquareString | null;
 	className?: string;
 	style?: CSSProperties;
 };
@@ -285,6 +296,14 @@ Called when the user completes a board move. Use this to update your game/rules
 
 When `true`, promotion automatically selects a queen. When omitted or `false`, the normal built-in promotion flow is used.
 
+### `checkSquare`
+
+Highlights the king's square when in check. Pass the king's square string (e.g. `'e1'`) to show a red glow; pass `null` or omit to clear it. The chessboard does not detect check itself — your rules layer (e.g. `chess.js`) is responsible for determining when and which square to highlight.
+
+```tsx
+<Chessboard checkSquare={chess.isCheck() ? kingSquare : null} ... />
+```
+
 ### `className` and `style`
 
 Applied to the outer container only. They are for layout, not board theming.
@@ -312,6 +331,36 @@ This keeps the integration boundary explicit:
 - The React component displays and collects user moves.
 - Mirasen handles board interaction, target feedback, promotion UI, special-move board updates, and animation.
 
+## Board handle (ref)
+
+`Chessboard` forwards a `ChessboardHandle` via `ref`. The handle is the full public surface of the underlying `@mirasen/chessboard` board instance — all extensions, all runtime methods, typed directly from the core package.
+
+```tsx
+import { Chessboard, type ChessboardHandle } from '@mirasen/react-chessboard';
+import { useEffect, useRef } from 'react';
+
+const boardRef = useRef<ChessboardHandle>(null);
+
+// once on mount — draw a circle via the annotations extension
+useEffect(() => {
+  boardRef.current?.extensions.annotations.circle('e4', { color: 'green' });
+}, []);
+
+<Chessboard ref={boardRef} position={...} />
+```
+
+The ref gives access to everything the core board exposes: `extensions.*`, `move(...)`, `setPosition(...)`, `setOrientation(...)`, `select(...)`, `getSnapshot()`, and more. When the core package adds a new extension, it is immediately accessible via `ref.current.extensions.<id>` — no wrapper update needed.
+
+**When to use ref vs props**
+
+Convenience props (`autoPromoteToQueen`, `checkSquare`, `onUIMove`) cover the most common declarative settings. Use the ref when:
+
+- you need an extension that has no convenience prop (e.g. `annotations`, `renderer` config)
+- you need to call an imperative method (`annotations.arrow(...)`, `select(...)`)
+- you want to read board state (`getSnapshot()`, `extensions.annotations.getCircles()`)
+
+**One channel per setting.** If a convenience prop already covers a setting, do not also write to the same extension property via ref in the same component — they write to the same underlying state and the last write wins.
+
 ## What you get out of the box
 
 The underlying Mirasen board provides the default first-party chessboard baseline:
@@ -322,6 +371,7 @@ The underlying Mirasen board provides the default first-party chessboard baselin
 - active-target feedback
 - legal move hints
 - last-move feedback
+- check square highlight
 - promotion UI
 - optional auto-promotion
 - animation for board-state changes

package/dist/Chessboard.d.ts

@@ -1,2 +1,2 @@
-import type { ChessboardProps } from './types.js';
-export declare function Chessboard({ position, externalMove, orientation, movability, onUIMove, autoPromoteToQueen, className, style }: ChessboardProps): import("react").JSX.Element;
+import type { ChessboardHandle, ChessboardProps } from './types.js';
+export declare const Chessboard: import("react").ForwardRefExoticComponent<ChessboardProps & import("react").RefAttributes<ChessboardHandle>>;

package/dist/Chessboard.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createBoard } from '@mirasen/chessboard';
-import { useEffect, useRef } from 'react';
-export function Chessboard({ position, externalMove, orientation, movability, onUIMove, autoPromoteToQueen, className, style }) {
+import { forwardRef, useEffect, useRef } from 'react';
+export const Chessboard = forwardRef(function Chessboard({ position, externalMove, orientation, movability, onUIMove, autoPromoteToQueen, checkSquare, className, style }, ref) {
     const containerRef = useRef(null);
     const boardRef = useRef(null);
     const onUIMoveRef = useRef(onUIMove);
@@ -24,6 +24,22 @@ export function Chessboard({ position, externalMove, orientation, movability, on
             boardRef.current = null;
         };
     }, []);
+    // Forward external ref to the same board instance
+    useEffect(() => {
+        const board = boardRef.current;
+        if (!board)
+            return;
+        if (typeof ref === 'function') {
+            ref(board);
+            return () => ref(null);
+        }
+        if (ref) {
+            ref.current = board;
+            return () => {
+                ref.current = null;
+            };
+        }
+    }, [ref]);
     // Position sync
     useEffect(() => {
         if (!boardRef.current)
@@ -66,5 +82,11 @@ export function Chessboard({ position, externalMove, orientation, movability, on
             return;
         boardRef.current.extensions.autoPromote.toQueen = autoPromoteToQueen ?? false;
     }, [autoPromoteToQueen]);
+    // checkSquare sync
+    useEffect(() => {
+        if (!boardRef.current)
+            return;
+        boardRef.current.extensions.check.square = checkSquare ?? null;
+    }, [checkSquare]);
     return _jsx("div", { ref: containerRef, className: className, style: style });
-}
+});

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { Chessboard } from './Chessboard.js';
-export type { BoardOrientation, ChessboardProps, ExternalMoveRequest, PositionRequest } from './types.js';
-export type { ColorInput, MovabilityInput, MoveOutput, MoveRequestInput, PositionInput } from '@mirasen/chessboard';
+export type { BoardOrientation, ChessboardHandle, ChessboardProps, ExternalMoveRequest, PositionRequest } from './types.js';
+export type { ColorInput, MovabilityInput, MoveOutput, MoveRequestInput, PositionInput, SquareString } from '@mirasen/chessboard';

package/dist/types.d.ts

@@ -1,5 +1,6 @@
-import type { ColorInput, MovabilityInput, MoveOutput, MoveRequestInput, PositionInput } from '@mirasen/chessboard';
+import type { Chessboard as CoreChessboard, ColorInput, MovabilityInput, MoveOutput, MoveRequestInput, PositionInput, SquareString } from '@mirasen/chessboard';
 import type { CSSProperties } from 'react';
+export type ChessboardHandle = CoreChessboard;
 export type BoardOrientation = ColorInput;
 export type PositionRequest = {
     id: string | number;
@@ -16,6 +17,7 @@ export type ChessboardProps = {
     movability?: MovabilityInput;
     onUIMove?: (move: MoveOutput) => void;
     autoPromoteToQueen?: boolean;
+    checkSquare?: SquareString | null;
     className?: string;
     style?: CSSProperties;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@mirasen/react-chessboard",
 	"description": "A React chessboard component with built-in interaction, promotion, animation, and chess.js integration.",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"license": "MIT",
 	"keywords": [
 		"mirasen",
@@ -56,7 +56,7 @@
 		"LICENSE"
 	],
 	"dependencies": {
-		"@mirasen/chessboard": "^1.1.3"
+		"@mirasen/chessboard": "^1.4.0"
 	},
 	"peerDependencies": {
 		"react": ">=18",
@@ -69,18 +69,18 @@
 		}
 	},
 	"devDependencies": {
-		"@changesets/cli": "^2.28.1",
+		"@changesets/cli": "^3.0.0",
 		"@eslint/compat": "^2.0.0",
 		"@eslint/js": "^10.0.1",
 		"@testing-library/react": "^16.3.2",
 		"@types/node": "^26.0.0",
 		"@types/react": "^18.3.0",
 		"@types/react-dom": "^18.3.0",
-		"@vitest/coverage-istanbul": "^4.0.3",
+		"@vitest/coverage-v8": "^4.0.3",
 		"eslint": "^10.0.2",
 		"eslint-config-prettier": "^10.1.2",
 		"globals": "^17.4.0",
-		"jsdom": "^29.1.1",
+		"jsdom": "^30.0.0",
 		"prettier": "^3.5.3",
 		"publint": "^0.3.11",
 		"react": "^18.3.1",