@echecs/react-board 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +109 -27
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.0.1] - 2026-04-09
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- removed non-existent `theme` prop and `BoardTheme` type from docs
|
|
8
|
+
- documented `turn`, `children`, `arrows`, `onSquareClick` props
|
|
9
|
+
- documented `squareCoords` function export
|
|
10
|
+
- documented all exported types (`Arrow`, `BoardProps`, `PieceKey`,
|
|
11
|
+
`PromotionDialogProps`, `PromotionPiece`, `SquareCoords`)
|
|
12
|
+
- fixed `PromotionDialog.onCancel` as optional
|
|
13
|
+
- documented all sound assets (`castle.mp3`, `check.mp3`, `game-end.mp3`)
|
|
14
|
+
|
|
3
15
|
## [1.0.0] - 2026-04-09
|
|
4
16
|
|
|
5
17
|
### Added
|
package/README.md
CHANGED
|
@@ -31,7 +31,6 @@ export function App() {
|
|
|
31
31
|
import { useState } from 'react';
|
|
32
32
|
import { Board } from '@echecs/react-board';
|
|
33
33
|
import type { MoveEvent } from '@echecs/react-board';
|
|
34
|
-
import type { Piece, Square } from '@echecs/position';
|
|
35
34
|
|
|
36
35
|
const STARTING_FEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
|
|
37
36
|
|
|
@@ -53,7 +52,6 @@ export function ChessGame() {
|
|
|
53
52
|
orientation={orientation}
|
|
54
53
|
position={position}
|
|
55
54
|
onMove={handleMove}
|
|
56
|
-
theme={{ darkSquare: '#b58863', lightSquare: '#f0d9b5' }}
|
|
57
55
|
/>
|
|
58
56
|
<button
|
|
59
57
|
onClick={() =>
|
|
@@ -69,37 +67,47 @@ export function ChessGame() {
|
|
|
69
67
|
|
|
70
68
|
## Props
|
|
71
69
|
|
|
72
|
-
| Prop
|
|
73
|
-
|
|
|
74
|
-
| `animate`
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
70
|
+
| Prop | Type | Default | Description |
|
|
71
|
+
| --------------- | ------------------------------ | ----------------- | ------------------------------------------------------ |
|
|
72
|
+
| `animate` | `boolean` | `true` | Enable CSS transition animation on piece moves |
|
|
73
|
+
| `arrows` | `Arrow[]` | — | Arrows to render on the board |
|
|
74
|
+
| `children` | `React.ReactNode` | — | Content rendered inside the board grid |
|
|
75
|
+
| `coordinates` | `boolean` | `true` | Show rank/file coordinate labels |
|
|
76
|
+
| `highlight` | `Square[]` | `[]` | Squares to highlight with an overlay |
|
|
77
|
+
| `interactive` | `boolean` | `true` | Enable drag & drop and click-to-move |
|
|
78
|
+
| `legalMoves` | `Map<Square, Square[]>` | — | Legal move map — restricts user interaction |
|
|
79
|
+
| `onMove` | `(move: MoveEvent) => boolean` | — | Called on every attempted move; return false to reject |
|
|
80
|
+
| `onSquareClick` | `(square: Square) => void` | — | Called when a square is clicked |
|
|
81
|
+
| `orientation` | `'white' \| 'black'` | `'white'` | Which side is at the bottom |
|
|
82
|
+
| `pieces` | `PieceSet` | `DEFAULT_PIECES` | Custom piece component record |
|
|
83
|
+
| `position` | `string \| Map<Square, Piece>` | starting position | FEN string or position map |
|
|
84
|
+
| `turn` | `'white' \| 'black'` | — | Restrict interaction to one colour's pieces |
|
|
84
85
|
|
|
85
86
|
## Theming
|
|
86
87
|
|
|
87
|
-
|
|
88
|
+
All visual styling is controlled via CSS custom properties. Set them on a parent
|
|
89
|
+
element or directly on the board container to override defaults.
|
|
88
90
|
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
coordinate: '#b58863',
|
|
97
|
-
border: 'transparent',
|
|
98
|
-
}}
|
|
99
|
-
/>
|
|
91
|
+
```css
|
|
92
|
+
.my-board {
|
|
93
|
+
--board-dark-square: #b58863;
|
|
94
|
+
--board-light-square: #f0d9b5;
|
|
95
|
+
--board-highlight: rgba(20, 85, 30, 0.5);
|
|
96
|
+
--board-legal-dot: rgba(0, 0, 0, 0.3);
|
|
97
|
+
}
|
|
100
98
|
```
|
|
101
99
|
|
|
102
|
-
|
|
100
|
+
| Variable | Default | Description |
|
|
101
|
+
| ------------------------------ | ---------------------------------------- | -------------------------------- |
|
|
102
|
+
| `--board-dark-square` | `#779952` | Dark square colour |
|
|
103
|
+
| `--board-light-square` | `#edeed1` | Light square colour |
|
|
104
|
+
| `--board-highlight` | `rgba(255, 255, 0, 0.4)` | Highlight overlay colour |
|
|
105
|
+
| `--board-legal-dot` | `rgba(0, 0, 0, 0.2)` | Legal move dot colour |
|
|
106
|
+
| `--board-coordinate-on-light` | `#779952` | Coordinate text on light squares |
|
|
107
|
+
| `--board-coordinate-on-dark` | `#edeed1` | Coordinate text on dark squares |
|
|
108
|
+
| `--board-coordinate-weight` | `600` | Coordinate font weight |
|
|
109
|
+
| `--board-promotion-background` | `rgba(0, 0, 0, 0.6)` | Promotion dialog background |
|
|
110
|
+
| `--board-drag-shadow` | `drop-shadow(0 4px 8px rgba(0,0,0,0.4))` | Drag ghost filter |
|
|
103
111
|
|
|
104
112
|
## Custom pieces
|
|
105
113
|
|
|
@@ -125,6 +133,80 @@ const myPieces: PieceSet = {
|
|
|
125
133
|
Piece key format: `'b' | 'w'` + `'B' | 'K' | 'N' | 'P' | 'Q' | 'R'` (e.g. `'wK'`
|
|
126
134
|
= white king, `'bP'` = black pawn).
|
|
127
135
|
|
|
136
|
+
## Sound assets
|
|
137
|
+
|
|
138
|
+
Bundled move sounds (Lichess standard set, MIT licensed). Import via subpath:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
import moveSound from '@echecs/react-board/sounds/move.mp3';
|
|
142
|
+
import captureSound from '@echecs/react-board/sounds/capture.mp3';
|
|
143
|
+
import castleSound from '@echecs/react-board/sounds/castle.mp3';
|
|
144
|
+
import checkSound from '@echecs/react-board/sounds/check.mp3';
|
|
145
|
+
import gameEndSound from '@echecs/react-board/sounds/game-end.mp3';
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| Subpath export | Description |
|
|
149
|
+
| ----------------------------------------- | ------------------- |
|
|
150
|
+
| `@echecs/react-board/sounds/move.mp3` | Standard piece move |
|
|
151
|
+
| `@echecs/react-board/sounds/capture.mp3` | Piece capture |
|
|
152
|
+
| `@echecs/react-board/sounds/castle.mp3` | Castling move |
|
|
153
|
+
| `@echecs/react-board/sounds/check.mp3` | Check |
|
|
154
|
+
| `@echecs/react-board/sounds/game-end.mp3` | Game over |
|
|
155
|
+
|
|
156
|
+
## Promotion dialog
|
|
157
|
+
|
|
158
|
+
`PromotionDialog` is exported separately for cases where you manage promotion
|
|
159
|
+
state yourself:
|
|
160
|
+
|
|
161
|
+
```tsx
|
|
162
|
+
import { PromotionDialog } from '@echecs/react-board';
|
|
163
|
+
|
|
164
|
+
<PromotionDialog
|
|
165
|
+
color="white"
|
|
166
|
+
squareSize={60}
|
|
167
|
+
onSelect={(piece) => console.log(piece)} // 'q' | 'r' | 'b' | 'n'
|
|
168
|
+
onCancel={() => console.log('cancelled')}
|
|
169
|
+
/>;
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### `PromotionDialog` props
|
|
173
|
+
|
|
174
|
+
| Prop | Type | Default | Description |
|
|
175
|
+
| ------------ | --------------------------------- | ---------------- | ------------------------------- |
|
|
176
|
+
| `color` | `'white' \| 'black'` | — | Which colour is promoting |
|
|
177
|
+
| `onCancel` | `() => void` | — | Optional. Called when dismissed |
|
|
178
|
+
| `onSelect` | `(piece: PromotionPiece) => void` | — | Called when a piece is clicked |
|
|
179
|
+
| `pieces` | `PieceSet` | `DEFAULT_PIECES` | Piece component set |
|
|
180
|
+
| `squareSize` | `number` | — | Square size in pixels |
|
|
181
|
+
|
|
182
|
+
## API reference
|
|
183
|
+
|
|
184
|
+
### `squareCoords(square, orientation)`
|
|
185
|
+
|
|
186
|
+
Returns `{ col, row }` — 1-based CSS grid coordinates for `square` given the
|
|
187
|
+
board `orientation`.
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
import { squareCoords } from '@echecs/react-board';
|
|
191
|
+
|
|
192
|
+
squareCoords('e4', 'white'); // { col: 5, row: 5 }
|
|
193
|
+
squareCoords('e4', 'black'); // { col: 4, row: 4 }
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Exported types
|
|
197
|
+
|
|
198
|
+
| Type | Description |
|
|
199
|
+
| ---------------------- | ---------------------------------------------------------------- |
|
|
200
|
+
| `Arrow` | `{ from: Square; to: Square; brush: string }` — arrow descriptor |
|
|
201
|
+
| `BoardProps` | All props accepted by `<Board />` |
|
|
202
|
+
| `MoveEvent` | `{ from, to, capture, promotion? }` — passed to `onMove` |
|
|
203
|
+
| `PieceComponent` | `React.ComponentType<{ size: number }>` — piece render contract |
|
|
204
|
+
| `PieceKey` | Union of all 12 piece keys (`'wK'`, `'bP'`, …) |
|
|
205
|
+
| `PieceSet` | `Record<PieceKey, PieceComponent>` — full piece set map |
|
|
206
|
+
| `PromotionDialogProps` | All props accepted by `<PromotionDialog />` |
|
|
207
|
+
| `PromotionPiece` | `'q' \| 'r' \| 'b' \| 'n'` — promotable piece |
|
|
208
|
+
| `SquareCoords` | `{ col: number; row: number }` — return type of `squareCoords` |
|
|
209
|
+
|
|
128
210
|
## License
|
|
129
211
|
|
|
130
212
|
MIT
|
package/package.json
CHANGED