feat: more features and docs

- docs on premoves
- add canDragPiece and squareStyles props
- prevent text highlighting on notation by default
- export all utils for consumers to use (docs coming later)

Author: Clariity

docs/B_HowToUse.mdx

@@ -3,13 +3,15 @@ import { Canvas, Meta } from '@storybook/blocks';
 import * as DefaultStories from './stories/Default.stories';
 import * as PlayVsRandomStories from './stories/PlayVsRandom.stories';
 import * as SparePiecesStories from './stories/SparePieces.stories';
+import * as PremovesStories from './stories/Premoves.stories';
 
 import * as AllowDraggingStories from './stories/options/AllowDragging.stories';
 import * as AllowDragOffBoardStories from './stories/options/AllowDragOffBoard.stories';
 import * as AlphaNotationStyleStories from './stories/options/AlphaNotationStyle.stories';
 import * as AnimationDurationInMsStories from './stories/options/AnimationDurationInMs.stories';
 import * as BoardOrientationStories from './stories/options/BoardOrientation.stories';
 import * as BoardStyleStories from './stories/options/BoardStyle.stories';
+import * as CanDragPieceStories from './stories/options/CanDragPiece.stories';
 import * as ChessboardColumnsStories from './stories/options/ChessboardColumns.stories';
 import * as ChessboardRowsStories from './stories/options/ChessboardRows.stories';
 import * as DarkSquareNotationStyleStories from './stories/options/DarkSquareNotationStyle.stories';
@@ -30,6 +32,7 @@ import * as PositionStories from './stories/options/Position.stories';
 import * as ShowAnimationsStories from './stories/options/ShowAnimations.stories';
 import * as ShowNotationStories from './stories/options/ShowNotation.stories';
 import * as SquareStyleStories from './stories/options/SquareStyle.stories';
+import * as SquareStylesStories from './stories/options/SquareStyles.stories';
 
 <Meta title="How to use" />
 
@@ -55,6 +58,7 @@ This page will show you how to use React Chessboard. It includes some basic and
   - [`options.animationDurationInMs`](#optionsanimationdurationinms)
   - [`options.boardOrientation`](#optionsboardorientation)
   - [`options.boardStyle`](#optionsboardstyle)
+  - [`options.canDragPiece`](#optionscandragpiece)
   - [`options.chessboardColumns`](#optionschessboardcolumns)
   - [`options.chessboardRows`](#optionschessboardrows)
   - [`options.darkSquareNotationStyle`](#optionsdarksquarenotationstyle)
@@ -75,6 +79,7 @@ This page will show you how to use React Chessboard. It includes some basic and
   - [`options.showAnimations`](#optionsshowanimations)
   - [`options.showNotation`](#optionsshownotation)
   - [`options.squareStyle`](#optionssquarestyle)
+  - [`options.squareStyles`](#optionssquarestyles)
 
 ## Basic and common examples
 
@@ -122,7 +127,9 @@ TODO
 
 ### Premoves
 
-TODO
+This example shows you how can you implement premoves with the component. Premoves are when you make a move and then before your opponent makes their move, you make a move to be played automatically after your opponent's move.
+
+<Canvas of={PremovesStories.Premoves} />
 
 ### Promotion piece selection
 
@@ -174,6 +181,7 @@ If you wish to display different styles of notation on different coloured square
   position: "absolute",
   bottom: 1,
   right: 4,
+  userSelect: 'none',
 }
 ```
 
@@ -227,6 +235,18 @@ Controls the styling of the entire chessboard container.
 
 <Canvas of={BoardStyleStories.BoardStyle} />
 
+### `options.canDragPiece`
+
+Controls whether a piece can be dragged.
+
+**Default value:** `undefined`
+
+**TypeScript type:** `({ isSparePiece: boolean, piece: { pieceType: string }, square: string | null }) => boolean`
+
+**Standard use case:** Restricting piece dragging to certain pieces or squares.
+
+<Canvas of={CanDragPieceStories.CanDragPiece} />
+
 ### `options.chessboardColumns`
 
 Controls the number of columns on the chessboard. If you set either of the row or column options above `9`, you will need to use the `positionObject` notation for the `position` prop, as `fen` notation only supports single digit columns.
@@ -363,6 +383,7 @@ If you wish to display different styles of notation on different coloured square
   position: "absolute",
   top: 2,
   left: 2,
+  userSelect: 'none',
 }
 ```
 
@@ -526,6 +547,18 @@ Controls the styling of all squares on the board, regardless of their colour.
 
 <Canvas of={SquareStyleStories.SquareStyle} />
 
+### `options.squareStyles`
+
+Controls the styling of individual squares on the board. This style will go over the top of any existing styles set with the [`squareStyle`](#optionssquarestyle) prop. This allows you to achieve effects like a background color over light and dark squares without needing to know whether the square is light or dark.
+
+**Default value:** `{}`
+
+**TypeScript type:** `Record<string, React.CSSProperties>`
+
+**Standard use case:** Customizing the appearance of specific squares such as for right clicks on squares or premoves.
+
+<Canvas of={SquareStylesStories.SquareStyles} />
+
 <div
   style={{
     textAlign: 'center',

docs/stories/Premoves.stories.tsx

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Chess } from 'chess.js';
+import { useState, useRef, useEffect } from 'react';
+
+import defaultMeta from './Default.stories';
+import { Chessboard, fenStringToPositionObject } from '../../src';
+import { PieceDropHandlerArgs, PieceHandlerArgs } from '../../src/types';
+
+const meta: Meta<typeof Chessboard> = {
+  ...defaultMeta,
+  title: 'stories/Premoves',
+} satisfies Meta<typeof Chessboard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Premoves: Story = {
+  render: () => {
+    const [chessGame, setChessGame] = useState(new Chess());
+    const [premoves, setPremoves] = useState<PieceDropHandlerArgs[]>([]);
+    const [showAnimations, setShowAnimations] = useState(true);
+    const chessGameRef = useRef(chessGame);
+    const premovesRef = useRef<PieceDropHandlerArgs[]>([]);
+
+    // update the ref when the game state changes
+    useEffect(() => {
+      chessGameRef.current = chessGame;
+    }, [chessGame]);
+
+    // make a random "CPU" move
+    function makeRandomMove() {
+      // get all possible moves
+      const possibleMoves = chessGameRef.current.moves();
+
+      // exit if the game is over
+      if (chessGameRef.current.isGameOver()) {
+        return;
+      }
+
+      // make a random move
+      const randomMove =
+        possibleMoves[Math.floor(Math.random() * possibleMoves.length)];
+      chessGameRef.current.move(randomMove);
+      setChessGame(new Chess(chessGameRef.current.fen()));
+
+      // if there is a premove, remove it from the list and make it once animation is complete
+      if (premovesRef.current.length > 0) {
+        const nextPlayerPremove = premovesRef.current[0];
+        premovesRef.current.splice(0, 1);
+
+        // wait for CPU move animation to complete
+        setTimeout(() => {
+          // execute the premove
+          const premoveSuccessful = onPieceDrop(nextPlayerPremove);
+
+          // if the premove was not successful, clear all premoves
+          if (!premoveSuccessful) {
+            premovesRef.current = [];
+          }
+
+          // update the premoves state
+          setPremoves([...premovesRef.current]);
+
+          // disable animations while clearing premoves
+          setShowAnimations(false);
+
+          // re-enable animations after a short delay
+          setTimeout(() => {
+            setShowAnimations(true);
+          }, 50);
+        }, 300);
+      }
+    }
+
+    // handle piece drop
+    function onPieceDrop({
+      sourceSquare,
+      targetSquare,
+      piece,
+    }: PieceDropHandlerArgs) {
+      // type narrow targetSquare potentially being null (e.g. if dropped off board) or user dropping piece onto same square
+      if (!targetSquare || sourceSquare === targetSquare) {
+        return false;
+      }
+
+      // check if a premove (piece isn't the color of the current player's turn)
+      const pieceColor = piece.pieceType[0]; // 'w' or 'b'
+      if (chessGameRef.current.turn() !== pieceColor) {
+        premovesRef.current.push({ sourceSquare, targetSquare, piece });
+        setPremoves([...premovesRef.current]);
+        // return early to stop processing the move and return true to not animate the move
+        return true;
+      }
+
+      // try to make the move
+      try {
+        chessGameRef.current.move({
+          from: sourceSquare,
+          to: targetSquare,
+          promotion: 'q', // always promote to a queen for example simplicity
+        });
+
+        // update the game state
+        setChessGame(new Chess(chessGameRef.current.fen()));
+
+        // make random cpu move after a slightly longer delay to allow user to premove
+        setTimeout(makeRandomMove, 3000);
+
+        // return true if the move was successful
+        return true;
+      } catch {
+        // return false if the move was not successful
+        return false;
+      }
+    }
+
+    // clear all premoves on right click
+    function onSquareRightClick() {
+      premovesRef.current = [];
+      setPremoves([...premovesRef.current]);
+
+      // disable animations while clearing premoves
+      setShowAnimations(false);
+
+      // re-enable animations after a short delay
+      setTimeout(() => {
+        setShowAnimations(true);
+      }, 50);
+    }
+
+    // only allow white pieces to be dragged
+    function canDragPiece({ piece }: PieceHandlerArgs) {
+      return piece.pieceType[0] === 'w';
+    }
+
+    // create a position object from the fen string to split the premoves from the game state
+    const position = fenStringToPositionObject(chessGame.fen(), 8, 8);
+    const squareStyles: Record<string, React.CSSProperties> = {};
+
+    // add premoves to the position object to show them on the board
+    for (const premove of premoves) {
+      delete position[premove.sourceSquare];
+      position[premove.targetSquare!] = {
+        pieceType: premove.piece.pieceType,
+      };
+      squareStyles[premove.sourceSquare] = {
+        backgroundColor: 'rgba(255,0,0,0.2)',
+      };
+      squareStyles[premove.targetSquare!] = {
+        backgroundColor: 'rgba(255,0,0,0.2)',
+      };
+    }
+
+    // set the chessboard options
+    const chessboardOptions = {
+      canDragPiece,
+      onPieceDrop,
+      onSquareRightClick,
+      position,
+      showAnimations,
+      squareStyles,
+    };
+
+    // render the chessboard
+    return <Chessboard options={chessboardOptions} />;
+  },
+};

docs/stories/options/CanDragPiece.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react';
+
+import defaultMeta from '../Default.stories';
+import { Chessboard } from '../../../src';
+import { PieceHandlerArgs } from '../../../src/types';
+
+const meta: Meta<typeof Chessboard> = {
+  ...defaultMeta,
+  title: 'stories/Options/AllowDragging',
+} satisfies Meta<typeof Chessboard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const CanDragPiece: Story = {
+  render: () => {
+    function canDragPiece({ piece }: PieceHandlerArgs) {
+      return piece.pieceType[0] === 'w';
+    }
+
+    // chessboard options
+    const chessboardOptions = {
+      canDragPiece,
+    };
+
+    // render
+    return (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '1rem',
+          alignItems: 'center',
+        }}
+      >
+        <Chessboard options={chessboardOptions} />
+
+        <p style={{ fontSize: '0.8rem', color: '#666' }}>
+          Only white pieces can be dragged
+        </p>
+      </div>
+    );
+  },
+};

docs/stories/options/SquareStyles.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import defaultMeta from '../Default.stories';
+import { Chessboard } from '../../../src';
+import { SquareHandlerArgs } from '../../../src/types';
+
+const meta: Meta<typeof Chessboard> = {
+  ...defaultMeta,
+  title: 'stories/Options/SquareStyle',
+} satisfies Meta<typeof Chessboard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const SquareStyles: Story = {
+  render: () => {
+    const [squareStyles, setSquareStyles] = useState<
+      Record<string, React.CSSProperties>
+    >({
+      e4: {
+        backgroundColor: 'rgba(255,0,0,0.2)',
+      },
+    });
+
+    function onSquareClick() {
+      setSquareStyles({});
+    }
+
+    // add or remove a style when a square is right clicked
+    function onSquareRightClick(args: SquareHandlerArgs) {
+      setSquareStyles((prev) => {
+        const newSquareStyles = { ...prev };
+        if (newSquareStyles[args.square]) {
+          delete newSquareStyles[args.square];
+        } else {
+          newSquareStyles[args.square] = {
+            backgroundColor: 'rgba(255,0,0,0.2)',
+          };
+        }
+        return newSquareStyles;
+      });
+    }
+
+    // chessboard options
+    const chessboardOptions = {
+      onSquareClick,
+      onSquareRightClick,
+      squareStyles,
+    };
+
+    // render
+    return (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '1rem',
+          alignItems: 'center',
+        }}
+      >
+        <Chessboard options={chessboardOptions} />
+
+        <p style={{ fontSize: '0.8rem', color: '#666' }}>
+          Right click on a square to add or remove a red background. Left click
+          to remove all red backgrounds.
+        </p>
+      </div>
+    );
+  },
+};