kokopu-react 3.0.2 → 3.1.0

package/src/chessboard/Chessboard.tsx

@@ -24,32 +24,21 @@
 
 import * as React from 'react';
 
-import { exception as kokopuException, MoveDescriptor, Position, Square, GameVariant, isSquare, isSquareCouple, isGameVariant } from 'kokopu';
+import { MoveDescriptor, Position, Square, isSquare, isSquareCouple } from 'kokopu';
 
 import { IllegalArgument } from '../exception';
-import { i18n } from '../i18n';
 import { sanitizeString, sanitizeBoolean, sanitizePartialObject, sanitizeInteger, sanitizeBoundedInteger, sanitizeOptional } from '../sanitization';
 import { MIN_SQUARE_SIZE, MAX_SQUARE_SIZE, Colorset, Pieceset, AnnotationColor, AnnotationSymbol, SquareMarkerSet, TextMarkerSet, ArrowMarkerSet,
 	isAnnotationColor, isAnnotationSymbol, parseSquareMarkers, parseTextMarkers, parseArrowMarkers } from '../types';
 
-import { colorsets, DEFAULT_COLORSET } from './colorsets';
-import { piecesets, DEFAULT_PIECESET } from './piecesets';
+import { StaticBoardGraphicProps, DynamicBoardGraphicProps, SmallScreenLimit, DEFAULT_SQUARE_SIZE, defaultDynamicBoardProps } from './BoardProperties';
+import { colorsets } from './colorsets';
+import { piecesets } from './piecesets';
 import { ChessboardImpl, chessboardSize } from './ChessboardImpl';
-import { ErrorBox } from '../errorbox/ErrorBox';
+import { parsePosition, parseMove } from '../errorbox/parsing';
 
 
-/**
- * Define a limit applicable to the parameters of a {@link Chessboard} on small-screen devices.
- */
-export interface SmallScreenLimit {
-	width: number;
-	squareSize?: number;
-	coordinateVisible?: boolean;
-	turnVisible?: boolean;
-}
-
-
-export interface ChessboardProps {
+export interface ChessboardProps extends DynamicBoardGraphicProps {
 
 	/**
 	 * Displayed position. Can be a [kokopu.Position](https://kokopu.yo35.org/docs/current/classes/Position.html) object,
@@ -64,8 +53,8 @@ export interface ChessboardProps {
 
 	/**
 	 * Displayed move (optional), defined either as a [kokopu.MoveDescriptor](https://kokopu.yo35.org/docs/current/classes/MoveDescriptor.html) object
-	 * or as a [SAN string](https://en.wikipedia.org/wiki/Algebraic_notation_(chess)) (e.g. `'Nf3'`). In both cases, it must represent
-	 * a legal move in position defined in attribute `position`.
+	 * or as a [SAN string](https://en.wikipedia.org/wiki/Algebraic_notation_(chess)) (e.g. `'Nf3'`). Use `'--'` for a null-move.
+	 * In all cases, the move must be a legal move in position defined in attribute `position`.
 	 */
 	move?: MoveDescriptor | string;
 
@@ -91,61 +80,6 @@ export interface ChessboardProps {
 	 */
 	flipped: boolean;
 
-	/**
-	 * Size of the squares (in pixels). Must be an integer between `Chessboard.minSquareSize()` and `Chessboard.maxSquareSize()`.
-	 */
-	squareSize: number;
-
-	/**
-	 * Whether the row and column coordinates are visible or not.
-	 */
-	coordinateVisible: boolean;
-
-	/**
-	 * Whether the turn flag is visible or not.
-	 */
-	turnVisible: boolean;
-
-	/**
-	 * Whether moves are highlighted with an arrow or not.
-	 */
-	moveArrowVisible: boolean;
-
-	/**
-	 * Color of the move arrow.
-	 */
-	moveArrowColor: AnnotationColor;
-
-	/**
-	 * Whether moves are animated or not.
-	 */
-	animated: boolean;
-
-	/**
-	 * Color theme ID. Must be a property of `Chessboard.colorsets()`.
-	 */
-	colorset: string;
-
-	/**
-	 * Piece theme ID. Must be a property of `Chessboard.piecesets()`.
-	 */
-	pieceset: string;
-
-	/**
-	 * Limits applicable on small-screen devices. For instance, if set to
-	 * ```
-	 * [
-	 *   { width: 768, squareSize: 40 },
-	 *   { width: 375, squareSize: 24, coordinateVisible: false }
-	 * ]
-	 * ```
-	 * then on screens with resolution ≤768 pixels, the square size will be limited to 40 (whatever the value
-	 * of the `squareSize` attribute); in addition, on screens with resolution ≤375 pixels, the square size
-	 * will be limited to 24 and the row and column coordinates will always be hidden (whatever the value of the
-	 * `coordinateVisible` attribute).
-	 */
-	smallScreenLimits?: SmallScreenLimit[];
-
 	/**
 	 * Type of action allowed with the mouse on the chessboard. If undefined, then the user cannot interact with the component.
 	 *
@@ -180,6 +114,18 @@ export interface ChessboardProps {
 	 * Callback invoked when a move is played (only if `interactionMode` is set to `'playMoves'`).
 	 */
 	onMovePlayed?: (move: string) => void;
+
+	/**
+	 * Optional component, to be rendered above the chessboard, and customized with the same square-size / coordinate-visible / turn-visible
+	 * parameter values as actually used for the chessboard (which may be different from what is defined in props because of small-screen limits).
+	 */
+	topComponent?: (attr: Pick<StaticBoardGraphicProps, 'squareSize' | 'coordinateVisible' | 'turnVisible'>) => JSX.Element;
+
+	/**
+	 * Optional component, to be rendered below the chessboard, and customized with the same square-size / coordinate-visible / turn-visible
+	 * parameter values as actually used for the chessboard (which may be different from what is defined in props because of small-screen limits).
+	 */
+	bottomComponent?: (attr: Pick<StaticBoardGraphicProps, 'squareSize' | 'coordinateVisible' | 'turnVisible'>) => JSX.Element;
 }
 
 
@@ -188,9 +134,6 @@ interface ChessboardState {
 }
 
 
-const DEFAULT_SQUARE_SIZE = 40;
-
-
 /**
  * SVG image representing a chessboard diagram. Optionally, the user may interact with the board (move pieces, click on squares...).
  * Annotations such as square markers or arrows can also be added to the board.
@@ -198,16 +141,9 @@ const DEFAULT_SQUARE_SIZE = 40;
 export class Chessboard extends React.Component<ChessboardProps, ChessboardState> {
 
 	static defaultProps: Partial<ChessboardProps> = {
+		...defaultDynamicBoardProps(),
 		position: 'start',
 		flipped: false,
-		squareSize: DEFAULT_SQUARE_SIZE,
-		coordinateVisible: true,
-		turnVisible: true,
-		moveArrowVisible: true,
-		moveArrowColor: 'b',
-		animated: false,
-		colorset: DEFAULT_COLORSET,
-		pieceset: DEFAULT_PIECESET,
 	};
 
 	private windowResizeListener = () => this.handleWindowResize();
@@ -234,16 +170,20 @@ export class Chessboard extends React.Component<ChessboardProps, ChessboardState
 	render() {
 
 		// Validate the position and move attributes.
-		const positionInfo = parsePosition(this.props.position);
+		const positionInfo = parsePosition(this.props.position, 'Chessboard');
 		if (positionInfo.error) {
-			return <ErrorBox title={i18n.INVALID_FEN_ERROR_TITLE} message={positionInfo.message} />;
+			return positionInfo.errorBox;
 		}
-		const position = positionInfo.position;
-		const moveInfo = parseMove(position, this.props.move);
+		let position = positionInfo.position;
+		const moveInfo = parseMove(position, this.props.move, 'Chessboard');
 		if (moveInfo.error) {
-			return <ErrorBox title={i18n.INVALID_NOTATION_ERROR_TITLE} message={moveInfo.message} />;
+			return moveInfo.errorBox;
+		}
+		const move = moveInfo.type === 'regular' ? moveInfo.move : undefined;
+		if (moveInfo.type === 'null-move') {
+			position = new Position(position);
+			position.playNullMove();
 		}
-		const move = moveInfo.move;
 
 		// Validate the markers
 		const sqm = parseMarkers(this.props.squareMarkers, 'squareMarkers', parseSquareMarkers, isSquare, isAnnotationColor);
@@ -274,6 +214,11 @@ export class Chessboard extends React.Component<ChessboardProps, ChessboardState
 		const actualSquareSize = computeSquareSizeForSmallScreens(squareSize, smallScreenLimits, this.state.windowWidth);
 		const actualCoordinateVisible = computeCoordinateVisibleForSmallScreens(coordinateVisible, smallScreenLimits, this.state.windowWidth);
 		const actualTurnVisible = computeTurnVisibleForSmallScreens(turnVisible, smallScreenLimits, this.state.windowWidth);
+		const auxilliaryComponentAttr = {
+			squareSize: actualSquareSize,
+			coordinateVisible: actualCoordinateVisible,
+			turnVisible: actualTurnVisible,
+		};
 
 		// Validate the interaction attributes and the callbacks.
 		const interactionMode = this.getInteractionModeAndValidateEditedArrowColor();
@@ -283,7 +228,8 @@ export class Chessboard extends React.Component<ChessboardProps, ChessboardState
 		// (mandatory to ensure that the move animation works properly and that the internal state of the component remains consistent).
 		const key = `${position.variant()}|${position.fen()}|${move ? position.notation(move) : ''}`;
 
-		return (
+		return (<>
+			{this.props.topComponent ? this.props.topComponent(auxilliaryComponentAttr) : undefined}
 			<ChessboardImpl key={key}
 				position={position} move={move} squareMarkers={sqm} textMarkers={txtm} arrowMarkers={arm} flipped={flipped}
 				squareSize={actualSquareSize} coordinateVisible={actualCoordinateVisible} turnVisible={actualTurnVisible}
@@ -292,7 +238,8 @@ export class Chessboard extends React.Component<ChessboardProps, ChessboardState
 				interactionMode={interactionMode} editedArrowColor={this.props.editedArrowColor}
 				onPieceMoved={onPieceMoved} onSquareClicked={onSquareClicked} onArrowEdited={onArrowEdited} onMovePlayed={onMovePlayed}
 			/>
-		);
+			{this.props.bottomComponent ? this.props.bottomComponent(auxilliaryComponentAttr) : undefined}
+		</>);
 	}
 
 	private getInteractionModeAndValidateEditedArrowColor() {
@@ -339,7 +286,7 @@ export class Chessboard extends React.Component<ChessboardProps, ChessboardState
 	 * Return the maximum square size that would allow the chessboard to fit in a rectangle of size `width x height`.
 	 */
 	static adaptSquareSize(width: number, height: number, attr?: Partial<Pick<ChessboardProps, 'coordinateVisible' | 'turnVisible' | 'smallScreenLimits'>>): number {
-		let { coordinateVisible, turnVisible, smallScreenLimits } = sanitizePartialObject(attr, () => new IllegalArgument('Chessboard.size()', 'attr'));
+		let { coordinateVisible, turnVisible, smallScreenLimits } = sanitizePartialObject(attr, () => new IllegalArgument('Chessboard.adaptSquareSize()', 'attr'));
 
 		// Sanitize the arguments.
 		width = sanitizeInteger(width, () => new IllegalArgument('Chessboard.adaptSquareSize()', 'width'));
@@ -473,82 +420,6 @@ function computeSmallScreenLimits<T>(smallScreenLimits: SmallScreenLimit[], wind
 }
 
 
-/**
- * Try to interpret the given object as a chess position.
- */
-function parsePosition(position: Position | string): { error: true, message: string } | { error: false, position: Position } {
-	if (position instanceof Position) {
-		return { error: false, position: position };
-	}
-	else if (position === 'start' || position === 'empty') {
-		return { error: false, position: new Position(position) };
-	}
-	else if (typeof position === 'string') {
-		try {
-			const { variant, fen } = splitGameVariantAndFEN(position);
-			const result = new Position(variant, 'empty');
-			result.fen(fen);
-			return { error: false, position: result };
-		}
-		catch (e) {
-			// istanbul ignore else
-			if (e instanceof kokopuException.InvalidFEN) {
-				return { error: true, message: e.message };
-			}
-			else {
-				throw e;
-			}
-		}
-	}
-	else {
-		throw new IllegalArgument('Chessboard', 'position');
-	}
-}
-
-
-/**
- * Look for an optional 'chess-variant:' prefix in the position attribute.
- */
-function splitGameVariantAndFEN(position: string): { variant: GameVariant, fen: string } {
-	const separatorIndex = position.indexOf(':');
-	if (separatorIndex < 0) {
-		return { variant: 'regular', fen: position };
-	}
-	const variant = position.substring(0, separatorIndex);
-	return isGameVariant(variant) ? { variant: variant, fen: position.substring(separatorIndex + 1) } : { variant: 'regular', fen: position };
-}
-
-
-/**
- * Try to interpret the given object `move` as a move descriptor based on the given position.
- */
-function parseMove(position: Position, move: MoveDescriptor | string | undefined): { error: true, message: string } | { error: false, move: MoveDescriptor | undefined } {
-	if (move === undefined || move === null) {
-		return { error: false, move: undefined };
-	}
-	else if (move instanceof MoveDescriptor) {
-		return { error: false, move: move };
-	}
-	else if (typeof move === 'string') {
-		try {
-			return { error: false, move: position.notation(move) };
-		}
-		catch (e) {
-			// istanbul ignore else
-			if (e instanceof kokopuException.InvalidNotation) {
-				return { error: true, message: e.message };
-			}
-			else {
-				throw e;
-			}
-		}
-	}
-	else {
-		throw new IllegalArgument('Chessboard', 'move');
-	}
-}
-
-
 /**
  * Try to interpret the given object as a list of markers.
  */

package/src/errorbox/parsing.tsx

@@ -0,0 +1,158 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    Kokopu-React - A React-based library of chess-related components.       *
+ *    <https://www.npmjs.com/package/kokopu-react>                            *
+ *    Copyright (C) 2021-2024  Yoann Le Montagner <yo35 -at- melix.net>       *
+ *                                                                            *
+ *    Kokopu-React is free software: you can redistribute it and/or           *
+ *    modify it under the terms of the GNU Lesser General Public License      *
+ *    as published by the Free Software Foundation, either version 3 of       *
+ *    the License, or (at your option) any later version.                     *
+ *                                                                            *
+ *    Kokopu-React is distributed in the hope that it will be useful,         *
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of          *
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the            *
+ *    GNU Lesser General Public License for more details.                     *
+ *                                                                            *
+ *    You should have received a copy of the GNU Lesser General               *
+ *    Public License along with this program. If not, see                     *
+ *    <http://www.gnu.org/licenses/>.                                         *
+ *                                                                            *
+ * -------------------------------------------------------------------------- */
+
+
+import * as React from 'react';
+
+import { exception as kokopuException, i18n as kokopuI18n, Database, Game, GameVariant, MoveDescriptor, Position, isGameVariant, pgnRead } from 'kokopu';
+
+import { IllegalArgument } from '../exception';
+import { i18n } from '../i18n';
+
+import { ErrorBox } from './ErrorBox';
+
+
+/**
+ * Try to interpret the given object as a chess position.
+ */
+export function parsePosition(position: Position | string, componentName: string):
+	{ error: true, errorBox: JSX.Element } | { error: false, position: Position }
+{
+	if (position instanceof Position) {
+		return { error: false, position: position };
+	}
+	else if (position === 'start' || position === 'empty') {
+		return { error: false, position: new Position(position) };
+	}
+	else if (typeof position === 'string') {
+		try {
+			const { variant, fen } = splitGameVariantAndFEN(position);
+			const result = new Position(variant, 'empty');
+			result.fen(fen);
+			return { error: false, position: result };
+		}
+		catch (e) {
+			// istanbul ignore else
+			if (e instanceof kokopuException.InvalidFEN) {
+				return { error: true, errorBox: <ErrorBox title={i18n.INVALID_FEN_ERROR_TITLE} message={e.message} /> };
+			}
+			else {
+				throw e;
+			}
+		}
+	}
+	else {
+		throw new IllegalArgument(componentName, 'position');
+	}
+}
+
+
+/**
+ * Look for an optional 'chess-variant:' prefix in the position attribute.
+ */
+function splitGameVariantAndFEN(position: string): { variant: GameVariant, fen: string } {
+	const separatorIndex = position.indexOf(':');
+	if (separatorIndex < 0) {
+		return { variant: 'regular', fen: position };
+	}
+	const variant = position.substring(0, separatorIndex);
+	return isGameVariant(variant) ? { variant: variant, fen: position.substring(separatorIndex + 1) } : { variant: 'regular', fen: position };
+}
+
+
+/**
+ * Try to interpret the given object `move` as a move descriptor based on the given position.
+ */
+export function parseMove(position: Position, move: MoveDescriptor | string | undefined, componentName: string):
+	{ error: true, errorBox: JSX.Element } | { error: false, type: 'none' | 'null-move' } | { error: false, type: 'regular', move: MoveDescriptor }
+{
+	if (move === undefined || move === null) {
+		return { error: false, type: 'none' };
+	}
+	else if (move instanceof MoveDescriptor) {
+		return { error: false, type: 'regular', move: move };
+	}
+	else if (typeof move === 'string') {
+		if (move === '--') {
+			if (position.isNullMoveLegal()) {
+				return { error: false, type: 'null-move' };
+			}
+			else {
+				return { error: true, errorBox: <ErrorBox title={i18n.INVALID_NOTATION_ERROR_TITLE} message={kokopuI18n.ILLEGAL_NULL_MOVE} /> };
+			}
+		}
+		else {
+			try {
+				return { error: false, type: 'regular', move: position.notation(move) };
+			}
+			catch (e) {
+				// istanbul ignore else
+				if (e instanceof kokopuException.InvalidNotation) {
+					return { error: true, errorBox: <ErrorBox title={i18n.INVALID_NOTATION_ERROR_TITLE} message={e.message} /> };
+				}
+				else {
+					throw e;
+				}
+			}
+		}
+	}
+	else {
+		throw new IllegalArgument(componentName, 'move');
+	}
+}
+
+
+/**
+ * Try to interpret the given object as a chess game.
+ */
+export function parseGame(game: Game | Database | string, gameIndex: number, componentName: string):
+	{ error: true, errorBox: JSX.Element } | { error: false, game: Game }
+{
+	if (game instanceof Game) {
+		return { error: false, game: game };
+	}
+	else if (game instanceof Database || typeof game === 'string') {
+		if (!Number.isInteger(gameIndex) || gameIndex < 0) {
+			throw new IllegalArgument(componentName, 'gameIndex');
+		}
+		try {
+			const result = game instanceof Database ? game.game(gameIndex) : pgnRead(game, gameIndex);
+			return { error: false, game: result };
+		}
+		catch (e) {
+			// istanbul ignore else
+			if (e instanceof kokopuException.InvalidPGN) {
+				return {
+					error: true,
+					errorBox: <ErrorBox title={i18n.INVALID_PGN_ERROR_TITLE} message={e.message} text={e.pgn} errorIndex={e.index} lineNumber={e.lineNumber} />,
+				};
+			}
+			else {
+				throw e;
+			}
+		}
+	}
+	else {
+		throw new IllegalArgument(componentName, 'game');
+	}
+}

package/src/i18n.ts

@@ -37,6 +37,13 @@ export let LINE = 'line {0}';
 export let INVALID_FEN_ERROR_TITLE = 'Invalid FEN string.';
 export let INVALID_NOTATION_ERROR_TITLE = 'Invalid move notation.';
 
+// Navigation board
+export let TOOLTIP_GO_FIRST = 'Go to the beginning of the game';
+export let TOOLTIP_GO_PREVIOUS = 'Go to the previous move';
+export let TOOLTIP_GO_NEXT = 'Go to the next move';
+export let TOOLTIP_GO_LAST = 'Go to the end of the game';
+export let TOOLTIP_FLIP = 'Flip the board';
+
 // Movetext
 export let PIECE_SYMBOLS = { 'K':'K', 'Q':'Q', 'R':'R', 'B':'B', 'N':'N', 'P':'P' };
 export let ANNOTATED_BY = 'Annotated by {0}';

package/src/index.ts

@@ -36,7 +36,11 @@ export { TextMarkerIcon, TextMarkerIconProps } from './icons/TextMarkerIcon';
 export { ArrowMarkerIcon, ArrowMarkerIconProps } from './icons/ArrowMarkerIcon';
 export { ChessPieceIcon, ChessPieceIconProps } from './icons/ChessPieceIcon';
 
-export { Chessboard, ChessboardProps, SmallScreenLimit } from './chessboard/Chessboard';
+export { SmallScreenLimit } from './chessboard/BoardProperties';
+export { Chessboard, ChessboardProps } from './chessboard/Chessboard';
 
 export { formatMove, moveFormatter } from './movetext/moveFormatter';
 export { Movetext, MovetextProps, MoveSelectEventOrigin } from './movetext/Movetext';
+
+export { firstNodeId, previousNodeId, nextNodeId, lastNodeId } from './navigationboard/NavigationField';
+export { NavigationBoard, NavigationBoardProps } from './navigationboard/NavigationBoard';

package/src/movetext/Movetext.css

@@ -108,16 +108,3 @@ div.kokopu-subVariation {
 	text-decoration: underline;
 	cursor: pointer;
 }
-
-.kokopu-focusFieldContainer {
-	position: fixed;
-	bottom: 0px;
-	right: 0px;
-	width: 0px;
-	height: 0px;
-	overflow: hidden;
-}
-
-.kokopu-focusField {
-	position: absolute; /* see #1 */
-}