Skip to content

Commit 428008b

Browse files
ClariityClariity
authored
feat: add clearArrowsOnPositionChange prop (#218)
1 parent 5ded2ac commit 428008b

File tree

4 files changed

+183
-43
lines changed

4 files changed

+183
-43
lines changed

‎docs/D_OptionsApi.mdx‎

Lines changed: 57 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import * as CanDragPieceStories from './stories/options/CanDragPiece.stories';
1616
import * as ChessboardColumnsStories from './stories/options/ChessboardColumns.stories';
1717
import * as ChessboardRowsStories from './stories/options/ChessboardRows.stories';
1818
import * as ClearArrowsOnClickStories from './stories/options/ClearArrowsOnClick.stories';
19+
import * as ClearArrowsOnPositionChangeStories from './stories/options/ClearArrowsOnPositionChange.stories';
1920
import * as DarkSquareNotationStyleStories from './stories/options/DarkSquareNotationStyle.stories';
2021
import * as DarkSquareStyleStories from './stories/options/DarkSquareStyle.stories';
2122
import * as DragActivationDistanceStories from './stories/options/DragActivationDistance.stories';
@@ -53,49 +54,50 @@ The component has a number of options that you can use to customise the componen
5354

5455
The code for these examples can be viewed by clicking the "Show code" button in the bottom right of the interactive examples. The code can also be viewed in the [GitHub repository](https://github.com/Clariity/react-chessboard/tree/main/docs/stories/options).
5556

56-
| Option | Description |
57-
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
58-
| [allowAutoScroll](#optionsallowautoscroll) | Controls auto-scrolling when dragging pieces near window edges |
59-
| [allowDragging](#optionsallowdragging) | Controls whether pieces can be dragged on the board |
60-
| [allowDragOffBoard](#optionsallowdragoffboard) | Controls whether pieces can be dragged off the board |
61-
| [allowDrawingArrows](#optionsallowdrawingarrows) | Controls whether arrows can be drawn by right-clicking and dragging |
62-
| [alphaNotationStyle](#optionsalphanotationstyle) | Controls styling of the alpha notation (a-h) |
63-
| [animationDurationInMs](#optionsanimationdurationinms) | Controls duration of piece movement animations |
64-
| [arrows](#optionsarrows) | Array of arrows to display on the board |
65-
| [arrowOptions](#optionsarrowoptions) | Controls styling and behavior of arrows |
66-
| [boardOrientation](#optionsboardorientation) | Sets orientation of the board ('white' or 'black') |
67-
| [boardStyle](#optionsboardstyle) | Controls styling of the main board container |
68-
| [canDragPiece](#optionscandragpiece) | Function to determine if a piece can be dragged |
69-
| [chessboardColumns](#optionschessboardcolumns) | Number of columns on the board |
70-
| [chessboardRows](#optionschessboardrows) | Number of rows on the board |
71-
| [clearArrowsOnClick](#optionscleararrowsonclick) | Controls whether arrows are cleared on board click |
72-
| [darkSquareNotationStyle](#optionsdarksquarenotationstyle) | Controls styling of notation on dark squares |
73-
| [darkSquareStyle](#optionsdarksquarestyle) | Controls styling of dark squares |
74-
| [dragActivationDistance](#optionsdragactivationdistance) | Distance in pixels before drag activation |
75-
| [draggingPieceGhostStyle](#optionsdraggingpieceghoststyle) | Controls styling of ghost piece while dragging |
76-
| [draggingPieceStyle](#optionsdraggingpiecestyle) | Controls styling of piece being dragged |
77-
| [dropSquareStyle](#optionsdropsquarestyle) | Controls styling of squares when dragging over them |
78-
| [id](#optionsid) | Sets the id of the chessboard component |
79-
| [lightSquareNotationStyle](#optionslightsquarenotationstyle) | Controls styling of notation on light squares |
80-
| [lightSquareStyle](#optionslightsquarestyle) | Controls styling of light squares |
81-
| [numericNotationStyle](#optionsnumericnotationstyle) | Controls styling of numeric notation (1-8) |
82-
| [onArrowsChange](#optionsonarrowschange) | Handler for when internal arrows change |
83-
| [onMouseOutSquare](#optionsonmouseoutsquare) | Handler for mouse leaving a square |
84-
| [onMouseOverSquare](#optionsonmouseoversquare) | Handler for mouse entering a square |
85-
| [onPieceClick](#optionsonpiececlick) | Handler for clicking a piece |
86-
| [onPieceDrag](#optionsonpiecedrag) | Handler for starting to drag a piece |
87-
| [onPieceDrop](#optionsonpiecedrop) | Handler for dropping a piece |
88-
| [onSquareClick](#optionsonsquareclick) | Handler for clicking a square |
89-
| [onSquareMouseDown](#optionsonsquaremousedown) | Handler for mouse button down on a square |
90-
| [onSquareMouseUp](#optionsonsquaremouseup) | Handler for mouse button up on a square |
91-
| [onSquareRightClick](#optionsonsquarerightclick) | Handler for right-clicking a square |
92-
| [pieces](#optionspieces) | Object mapping piece types to React components |
93-
| [position](#optionsposition) | Current position on the board (FEN string or position object) |
94-
| [showAnimations](#optionsshowanimations) | Controls whether piece movements are animated |
95-
| [showNotation](#optionsshownotation) | Controls whether board notation is displayed |
96-
| [squareRenderer](#optionssquarerenderer) | Controls the rendering of squares on the board |
97-
| [squareStyle](#optionssquarestyle) | Base styling applied to all squares |
98-
| [squareStyles](#optionssquarestyles) | Object mapping squares to custom styles |
57+
| Option | Description |
58+
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
59+
| [allowAutoScroll](#optionsallowautoscroll) | Controls auto-scrolling when dragging pieces near window edges |
60+
| [allowDragging](#optionsallowdragging) | Controls whether pieces can be dragged on the board |
61+
| [allowDragOffBoard](#optionsallowdragoffboard) | Controls whether pieces can be dragged off the board |
62+
| [allowDrawingArrows](#optionsallowdrawingarrows) | Controls whether arrows can be drawn by right-clicking and dragging |
63+
| [alphaNotationStyle](#optionsalphanotationstyle) | Controls styling of the alpha notation (a-h) |
64+
| [animationDurationInMs](#optionsanimationdurationinms) | Controls duration of piece movement animations |
65+
| [arrows](#optionsarrows) | Array of arrows to display on the board |
66+
| [arrowOptions](#optionsarrowoptions) | Controls styling and behavior of arrows |
67+
| [boardOrientation](#optionsboardorientation) | Sets orientation of the board ('white' or 'black') |
68+
| [boardStyle](#optionsboardstyle) | Controls styling of the main board container |
69+
| [canDragPiece](#optionscandragpiece) | Function to determine if a piece can be dragged |
70+
| [chessboardColumns](#optionschessboardcolumns) | Number of columns on the board |
71+
| [chessboardRows](#optionschessboardrows) | Number of rows on the board |
72+
| [clearArrowsOnClick](#optionscleararrowsonclick) | Controls whether arrows are cleared on board click |
73+
| [clearArrowsOnPositionChange](#optionscleararrowsonpositionchange) | Controls whether arrows are cleared on position change |
74+
| [darkSquareNotationStyle](#optionsdarksquarenotationstyle) | Controls styling of notation on dark squares |
75+
| [darkSquareStyle](#optionsdarksquarestyle) | Controls styling of dark squares |
76+
| [dragActivationDistance](#optionsdragactivationdistance) | Distance in pixels before drag activation |
77+
| [draggingPieceGhostStyle](#optionsdraggingpieceghoststyle) | Controls styling of ghost piece while dragging |
78+
| [draggingPieceStyle](#optionsdraggingpiecestyle) | Controls styling of piece being dragged |
79+
| [dropSquareStyle](#optionsdropsquarestyle) | Controls styling of squares when dragging over them |
80+
| [id](#optionsid) | Sets the id of the chessboard component |
81+
| [lightSquareNotationStyle](#optionslightsquarenotationstyle) | Controls styling of notation on light squares |
82+
| [lightSquareStyle](#optionslightsquarestyle) | Controls styling of light squares |
83+
| [numericNotationStyle](#optionsnumericnotationstyle) | Controls styling of numeric notation (1-8) |
84+
| [onArrowsChange](#optionsonarrowschange) | Handler for when internal arrows change |
85+
| [onMouseOutSquare](#optionsonmouseoutsquare) | Handler for mouse leaving a square |
86+
| [onMouseOverSquare](#optionsonmouseoversquare) | Handler for mouse entering a square |
87+
| [onPieceClick](#optionsonpiececlick) | Handler for clicking a piece |
88+
| [onPieceDrag](#optionsonpiecedrag) | Handler for starting to drag a piece |
89+
| [onPieceDrop](#optionsonpiecedrop) | Handler for dropping a piece |
90+
| [onSquareClick](#optionsonsquareclick) | Handler for clicking a square |
91+
| [onSquareMouseDown](#optionsonsquaremousedown) | Handler for mouse button down on a square |
92+
| [onSquareMouseUp](#optionsonsquaremouseup) | Handler for mouse button up on a square |
93+
| [onSquareRightClick](#optionsonsquarerightclick) | Handler for right-clicking a square |
94+
| [pieces](#optionspieces) | Object mapping piece types to React components |
95+
| [position](#optionsposition) | Current position on the board (FEN string or position object) |
96+
| [showAnimations](#optionsshowanimations) | Controls whether piece movements are animated |
97+
| [showNotation](#optionsshownotation) | Controls whether board notation is displayed |
98+
| [squareRenderer](#optionssquarerenderer) | Controls the rendering of squares on the board |
99+
| [squareStyle](#optionssquarestyle) | Base styling applied to all squares |
100+
| [squareStyles](#optionssquarestyles) | Object mapping squares to custom styles |
99101

100102
## Options
101103

@@ -380,6 +382,18 @@ Controls whether **internal** arrows are cleared when a square is clicked. If yo
380382

381383
<Canvas of={ClearArrowsOnClickStories.ClearArrowsOnClick} />
382384

385+
### `options.clearArrowsOnPositionChange`
386+
387+
Controls whether **internal** arrows are cleared when the position changes. If you are passing in external arrows via the [`arrows`](#optionsarrows) prop, these will not be automatically cleared when the position changes. Instead, you will need to clear them manually when updating the position and pass in a new value for the [`arrows`](#optionsarrows) prop.
388+
389+
**Default value:** `true`
390+
391+
**TypeScript type:** `boolean`
392+
393+
**Standard use case:** Disabling the ability to clear internal arrows when the position changes.
394+
395+
<Canvas of={ClearArrowsOnPositionChangeStories.ClearArrowsOnPositionChange} />
396+
383397
### `options.darkSquareNotationStyle`
384398

385399
Controls the styling of notation on dark squares. If you wish to instead hide the notation, set [`showNotation`](#optionsshownotation) to `false`.

‎docs/G_UpgradeToV5.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ The v5 release includes significant changes to the API. Here's a detailed compar
8888
- `allowAutoScroll`: Controls whether dragging a piece near the edge of the window will automatically scroll the window
8989
- `chessboardRows` and `chessboardColumns`: Control board dimensions
9090
- `clearArrowsOnClick`: Control whether to clear arrows when clicking on the board
91+
- `clearArrowsOnPositionChange`: Control whether to clear arrows when the position changes
9192
- `dragActivationDistance`: Control the distance from the cursor to the piece to activate dragging
9293
- `draggingPieceGhostStyle`: Style the ghost piece while being dragged
9394
- `draggingPieceStyle`: Style the piece while being dragged

‎docs/stories/options/ClearArrowsOnPositionChange.stories.tsx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
import type { Meta, StoryObj } from '@storybook/react';
2+
import { useState } from 'react';
3+
4+
import defaultMeta from '../basic-examples/Default.stories';
5+
import { Chessboard } from '../../../src';
6+
7+
const meta: Meta<typeof Chessboard> = {
8+
...defaultMeta,
9+
title: 'stories/Options/ClearArrowsOnPositionChange',
10+
} satisfies Meta<typeof Chessboard>;
11+
12+
export default meta;
13+
type Story = StoryObj<typeof meta>;
14+
15+
export const ClearArrowsOnPositionChange: Story = {
16+
render: () => {
17+
const [clearArrowsOnPositionChange, setClearArrowsOnPositionChange] =
18+
useState(true);
19+
const [arrows] = useState([
20+
{ startSquare: 'e2', endSquare: 'e4', color: 'red' },
21+
{ startSquare: 'g1', endSquare: 'f3', color: 'blue' },
22+
]);
23+
const [position, setPosition] = useState(
24+
'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR',
25+
);
26+
27+
// generate random FEN position
28+
function generateRandomFen() {
29+
const pieces = [
30+
'r',
31+
'n',
32+
'b',
33+
'q',
34+
'k',
35+
'p',
36+
'R',
37+
'N',
38+
'B',
39+
'Q',
40+
'K',
41+
'P',
42+
];
43+
let fen = '';
44+
45+
// create 8 rows of random pieces
46+
for (let i = 0; i < 8; i++) {
47+
let emptyCount = 0;
48+
49+
// create 8 columns of random pieces or empty squares
50+
for (let j = 0; j < 8; j++) {
51+
if (Math.random() < 0.2) {
52+
if (emptyCount > 0) {
53+
fen += emptyCount;
54+
emptyCount = 0;
55+
}
56+
57+
fen += pieces[Math.floor(Math.random() * pieces.length)];
58+
} else {
59+
emptyCount++;
60+
}
61+
}
62+
63+
// add empty count to FEN string if there are empty squares
64+
if (emptyCount > 0) {
65+
fen += emptyCount;
66+
}
67+
68+
// add slash between rows
69+
if (i < 7) {
70+
fen += '/';
71+
}
72+
}
73+
74+
// set the position
75+
setPosition(fen);
76+
}
77+
78+
// chessboard options
79+
const chessboardOptions = {
80+
arrows,
81+
clearArrowsOnPositionChange,
82+
id: 'clear-arrows-on-click',
83+
position,
84+
};
85+
86+
// render
87+
return (
88+
<div
89+
style={{
90+
display: 'flex',
91+
flexDirection: 'column',
92+
gap: '1rem',
93+
alignItems: 'center',
94+
}}
95+
>
96+
<label>
97+
<input
98+
type="checkbox"
99+
checked={clearArrowsOnPositionChange}
100+
onChange={(e) => setClearArrowsOnPositionChange(e.target.checked)}
101+
/>
102+
Clear arrows on position change
103+
</label>
104+
105+
<button onClick={generateRandomFen}>
106+
Generate random FEN position
107+
</button>
108+
109+
<Chessboard options={chessboardOptions} />
110+
111+
<p style={{ fontSize: '0.8rem', color: '#666' }}>
112+
Toggle the checkbox to enable/disable clearing arrows when the
113+
position changes.
114+
</p>
115+
</div>
116+
);
117+
},
118+
};

‎src/ChessboardProvider.tsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,7 @@ export type ChessboardOptions = {
176176
arrows?: Arrow[];
177177
arrowOptions?: typeof defaultArrowOptions;
178178
clearArrowsOnClick?: boolean;
179+
clearArrowsOnPositionChange?: boolean;
179180

180181
// handlers
181182
canDragPiece?: ({ isSparePiece, piece, square }: PieceHandlerArgs) => boolean;
@@ -255,6 +256,7 @@ export function ChessboardProvider({
255256
arrows = [],
256257
arrowOptions = defaultArrowOptions,
257258
clearArrowsOnClick = true,
259+
clearArrowsOnPositionChange = true,
258260

259261
// handlers
260262
canDragPiece,
@@ -322,6 +324,11 @@ export function ChessboardProvider({
322324
? fenStringToPositionObject(position, chessboardRows, chessboardColumns)
323325
: position;
324326

327+
// clear internal arrows on position change
328+
if (clearArrowsOnPositionChange) {
329+
clearArrows();
330+
}
331+
325332
// if no animation, just set the position
326333
if (!showAnimations) {
327334
setCurrentPosition(newPosition);

0 commit comments

Comments
 (0)