kokopu-react 3.0.2 → 3.2.0

package/src/navigationboard/NavigationBoard.tsx

@@ -0,0 +1,350 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    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 { Database, Game, Node as GameNode, Variation } from 'kokopu';
+
+import { IllegalArgument } from '../exception';
+import { i18n } from '../i18n';
+import { sanitizeBoolean, sanitizeOptional, sanitizeString } from '../sanitization';
+
+import { DynamicBoardGraphicProps, defaultDynamicBoardProps } from '../chessboard/BoardProperties';
+import { Chessboard } from '../chessboard/Chessboard';
+import { parseGame } from '../errorbox/parsing';
+import { NavigationField, firstNodeId, previousNodeId, nextNodeId, lastNodeId } from '../navigationboard/NavigationField';
+import { GO_FIRST_ICON_PATH, GO_PREVIOUS_ICON_PATH, GO_NEXT_ICON_PATH, GO_LAST_ICON_PATH, PLAY_ICON_PATH, STOP_ICON_PATH, FLIP_ICON_PATH } from './iconPaths';
+import { NavigationButton, NavigationButtonList, isNavigationButton } from './NavigationButton';
+import { NavigationToolbar } from './NavigationToolbar';
+
+
+const INTER_MOVE_DURATION = 1000;
+
+
+export interface NavigationBoardProps extends DynamicBoardGraphicProps {
+
+    /**
+     * Displayed game. Can be a [kokopu.Game](https://kokopu.yo35.org/docs/current/classes/Game.html) object,
+     * a [kokopu.Database](https://kokopu.yo35.org/docs/current/classes/Database.html) object,
+     * or a [PGN string](https://en.wikipedia.org/wiki/Portable_Game_Notation).
+     */
+    game: Game | Database | string;
+
+    /**
+     * Index of the game to display (only if attribute `game` is a [kokopu.Database](https://kokopu.yo35.org/docs/current/classes/Database.html)
+     * or a [PGN string](https://en.wikipedia.org/wiki/Portable_Game_Notation)): `0` for the first game of the database/PGN, `1` for the second one, etc.
+     * If omitted, the first game of the database/PGN is displayed.
+     */
+    gameIndex: number;
+
+    /**
+     * ID of the move initially selected (or `'start'`/`'end'` for the beginning/end of the main variation) when the component is uncontrolled.
+     * Use [kokopu.Node#id](https://kokopu.yo35.org/docs/current/classes/Node.html#id) to get the ID of a game move.
+     * Ignored if the `nodeId` attribute is provided.
+     */
+    initialNodeId: string;
+
+    /**
+     * ID of the selected move (or `'start'`/`'end'` for the beginning/end of the main variation).
+     * Use [kokopu.Node#id](https://kokopu.yo35.org/docs/current/classes/Node.html#id) to get the ID of a game move.
+     * If provided (i.e. if the component is controlled), the attribute `onNodeIdChanged` must be provided as well.
+     */
+    nodeId?: string;
+
+    /**
+     * Callback invoked in controlled-component mode, when the user changes the selected move.
+     *
+     * @param nodeId - ID of the selected move (as returned by [kokopu.Node#id](https://kokopu.yo35.org/docs/current/classes/Node.html#id)),
+     *                 or `'start'` for the beginning of the main variation.
+     */
+    onNodeIdChanged?: (nodeId: string) => void;
+
+    /**
+     * Whether auto-play is initially enabled or not.
+     * Ignored if the `isPlaying` attribute is provided.
+     */
+    initialIsPlaying: boolean;
+
+    /**
+     * Whether auto-play is enabled or not.
+     * If provided (i.e. if the is-playing state is controlled), the attribute `onIsPlayingChanged` must be provided as well.
+     */
+    isPlaying?: boolean;
+
+    /**
+     * Callback invoked in controlled-is-playing-state mode, when the user clicks on the play/stop button.
+     *
+     * @param isPlaying - New is-playing state.
+     */
+    onIsPlayingChanged?: (isPlaying: boolean) => void;
+
+    /**
+     * Whether the board is initially flipped (i.e. seen from Black's point of view) or not, when the flip state is uncontrolled.
+     * Ignored if the `flipped` attribute is provided.
+     */
+    initialFlipped: boolean;
+
+    /**
+     * Whether the board is flipped (i.e. seen from Black's point of view) or not.
+     * If provided (i.e. if the flip state is controlled), the attribute `onFlippedChanged` must be provided as well.
+     */
+    flipped?: boolean;
+
+    /**
+     * Callback invoked in controlled-flip-state mode, when the user flips the board.
+     *
+     * @param flipped - New flip state.
+     */
+    onFlippedChanged?: (flipped: boolean) => void;
+
+    /**
+     * Whether the play/stop button is visible or not in the toolbar.
+     */
+    playButtonVisible: boolean;
+
+    /**
+     * Whether the flip button is visible or not in the toolbar.
+     */
+    flipButtonVisible: boolean;
+
+    /**
+     * Additional buttons to be added to the toolbar.
+     */
+    additionalButtons: NavigationButton | NavigationButtonList;
+}
+
+
+interface NavigationBoardState {
+    nodeIdAsUncontrolled: string;
+    isPlayingAsUncontrolled: boolean;
+    flippedAsUncontrolled: boolean;
+}
+
+
+/**
+ * Component displaying the positions occurring in a chess game, with navigation buttons to browse these positions.
+ */
+export class NavigationBoard extends React.Component<NavigationBoardProps, NavigationBoardState> {
+
+    static defaultProps = {
+        ...defaultDynamicBoardProps(),
+        game: new Game(),
+        gameIndex: 0,
+        initialNodeId: 'start',
+        initialIsPlaying: false,
+        initialFlipped: false,
+        playButtonVisible: false,
+        flipButtonVisible: true,
+        additionalButtons: [],
+    };
+
+    private navigationFieldRef: React.RefObject<NavigationField> = React.createRef();
+    private timeoutId?: number;
+
+    constructor(props: NavigationBoardProps) {
+        super(props);
+        this.state = {
+            nodeIdAsUncontrolled: sanitizeString(props.initialNodeId),
+            isPlayingAsUncontrolled: sanitizeBoolean(props.initialIsPlaying),
+            flippedAsUncontrolled: sanitizeBoolean(props.initialFlipped),
+        };
+    }
+
+    componentWillUnmount() {
+        this.cancelCurrentTimeout();
+    }
+
+    render() {
+        this.cancelCurrentTimeout();
+
+        // Validate the game and game-index attributes.
+        const info = parseGame(this.props.game, this.props.gameIndex, 'NavigationBoard');
+        if (info.error) {
+            return info.errorBox;
+        }
+
+        // Fetch the current node/variation.
+        const currentNodeId = sanitizeOptional(this.props.nodeId, sanitizeString) ?? this.state.nodeIdAsUncontrolled;
+        const currentNode = info.game.findById(currentNodeId) ?? info.game.mainVariation();
+
+        // State flags.
+        const isPlaying = sanitizeOptional(this.props.isPlaying, sanitizeBoolean) ?? this.state.isPlayingAsUncontrolled;
+        const flipped = sanitizeOptional(this.props.flipped, sanitizeBoolean) ?? this.state.flippedAsUncontrolled;
+
+        return (
+            <div className="kokopu-navigationBoard">
+                {this.renderBoard(info.game, currentNode, isPlaying, flipped)}
+                {this.renderNavigationField(info.game, currentNode.id())}
+            </div>
+        );
+    }
+
+    private renderBoard(game: Game, node: GameNode | Variation, isPlaying: boolean, flipped: boolean) {
+        const position = node instanceof GameNode ? node.positionBefore() : node.initialPosition();
+        const move = node instanceof GameNode ? node.notation() : undefined;
+        return <Chessboard
+            position={position} move={move} flipped={flipped}
+            squareMarkers={node.tag('csl')} arrowMarkers={node.tag('cal')} textMarkers={node.tag('ctl')}
+            squareSize={this.props.squareSize}
+            coordinateVisible={this.props.coordinateVisible}
+            turnVisible={this.props.turnVisible}
+            colorset={this.props.colorset}
+            pieceset={this.props.pieceset}
+            smallScreenLimits={this.props.smallScreenLimits}
+            moveArrowVisible={this.props.moveArrowVisible}
+            moveArrowColor={this.props.moveArrowColor}
+            animated={this.props.animated}
+            bottomComponent={({ squareSize }) => this.renderToolbar(game, node, squareSize, isPlaying)}
+        />;
+    }
+
+    private renderNavigationField(game: Game, currentNodeId: string) {
+        return <NavigationField ref={this.navigationFieldRef}
+            onFirstPressed={() => this.handleNavClicked(firstNodeId(game, currentNodeId))}
+            onPreviousPressed={() => this.handleNavClicked(previousNodeId(game, currentNodeId))}
+            onNextPressed={() => this.handleNavClicked(nextNodeId(game, currentNodeId))}
+            onLastPressed={() => this.handleNavClicked(lastNodeId(game, currentNodeId))}
+        />;
+    }
+
+    private renderToolbar(game: Game, node: GameNode | Variation, squareSize: number, isPlaying: boolean) {
+        const buttons: NavigationButtonList = [];
+
+        // Core navigation buttons
+        const currentNodeId = node.id();
+        const hasPrevious = currentNodeId !== 'start';
+        const hasNext = (node instanceof Variation ? node.first() : node.next()) !== undefined;
+        buttons.push({ iconPath: GO_FIRST_ICON_PATH, tooltip: i18n.TOOLTIP_GO_FIRST, enabled: hasPrevious, onClick: () => this.handleNavClicked(firstNodeId(game, currentNodeId)) });
+        buttons.push({ iconPath: GO_PREVIOUS_ICON_PATH, tooltip: i18n.TOOLTIP_GO_PREVIOUS, enabled: hasPrevious, onClick: () => this.handleNavClicked(previousNodeId(game, currentNodeId)) });
+        if (sanitizeBoolean(this.props.playButtonVisible)) {
+            buttons.push({ iconPath: isPlaying ? STOP_ICON_PATH : PLAY_ICON_PATH, tooltip: i18n.TOOLTIP_PLAY_STOP, enabled: hasNext, onClick: () => this.handlePlayStopClicked(!isPlaying) });
+        }
+        buttons.push({ iconPath: GO_NEXT_ICON_PATH, tooltip: i18n.TOOLTIP_GO_NEXT, enabled: hasNext, onClick: () => this.handleNavClicked(nextNodeId(game, currentNodeId)) });
+        buttons.push({ iconPath: GO_LAST_ICON_PATH, tooltip: i18n.TOOLTIP_GO_LAST, enabled: hasNext, onClick: () => this.handleNavClicked(lastNodeId(game, currentNodeId)) });
+        buttons.push('spacer');
+        if (sanitizeBoolean(this.props.flipButtonVisible)) {
+            buttons.push({ iconPath: FLIP_ICON_PATH, tooltip: i18n.TOOLTIP_FLIP, onClick: () => this.handleFlipButtonClicked() });
+        }
+        buttons.push('spacer');
+
+        // Schedule the next transition if auto-play is enabled.
+        if (isPlaying) {
+            if (hasNext) {
+                this.timeoutId = window.setTimeout(() => this.handleNavClicked(nextNodeId(game, currentNodeId), false), INTER_MOVE_DURATION);
+            }
+            else {
+                // ... or stop the auto-play if at the end of the game.
+                this.timeoutId = window.setTimeout(() => this.handlePlayStopClicked(false, false), 0);
+            }
+        }
+
+        // Additional buttons.
+        const additionalButtons = sanitizeNavigationButtonList(this.props.additionalButtons, () => new IllegalArgument('NavigationBoard', 'additionalButtons'));
+        for (const button of additionalButtons) {
+            buttons.push(button);
+        }
+
+        return <NavigationToolbar squareSize={squareSize} buttons={buttons} />;
+    }
+
+    private handleNavClicked(targetNodeId: string | undefined, forceFocus = true) {
+        if (forceFocus) {
+            this.focus();
+        }
+        if (targetNodeId === undefined) {
+            return;
+        }
+
+        if (this.props.nodeId === undefined) { // uncontrolled-component behavior
+            this.setState({ nodeIdAsUncontrolled: targetNodeId });
+        }
+        else if (this.props.onNodeIdChanged) { // controlled-component behavior
+            this.props.onNodeIdChanged(targetNodeId);
+        }
+    }
+
+    private handlePlayStopClicked(targetIsPlaying: boolean, forceFocus = true) {
+        if (forceFocus) {
+            this.focus();
+        }
+        if (this.props.isPlaying === undefined) { // uncontrolled is-playing state
+            this.setState({ isPlayingAsUncontrolled: targetIsPlaying });
+        }
+        else if (this.props.onIsPlayingChanged) { // controlled is-playing state
+            this.props.onIsPlayingChanged(targetIsPlaying);
+        }
+    }
+
+    private handleFlipButtonClicked() {
+        this.focus();
+        if (this.props.flipped === undefined) { // uncontrolled flip state
+            this.setState({ flippedAsUncontrolled: !this.state.flippedAsUncontrolled });
+        }
+        else if (this.props.onFlippedChanged) { // controlled flip state
+            this.props.onFlippedChanged(!this.props.flipped);
+        }
+    }
+
+    private cancelCurrentTimeout() {
+        if (this.timeoutId !== undefined) {
+            window.clearTimeout(this.timeoutId);
+            this.timeoutId = undefined;
+        }
+    }
+
+    /**
+     * Set the focus to the current component.
+     *
+     * @public
+     */
+    focus(): void {
+        const target = this.navigationFieldRef.current;
+        // istanbul ignore else
+        if (target) {
+            target.focus();
+        }
+    }
+
+}
+
+
+/**
+ * Sanitization method for the additional button parameter.
+ */
+function sanitizeNavigationButtonList(type: NavigationButton | NavigationButtonList, exceptionBuilder: () => IllegalArgument): NavigationButtonList {
+    if (Array.isArray(type)) {
+        return type.map(t => {
+            if (t !== 'spacer' && !isNavigationButton(t)) {
+                throw exceptionBuilder();
+            }
+            return t;
+        });
+    }
+    else if (isNavigationButton(type)) {
+        return [ type ];
+    }
+    else {
+        throw exceptionBuilder();
+    }
+}

package/src/navigationboard/NavigationButton.ts

@@ -0,0 +1,72 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    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/>.                                         *
+ *                                                                            *
+ * -------------------------------------------------------------------------- */
+
+
+/**
+ * Descriptor for additional buttons to be added to the toolbar of {@link NavigationBoard}.
+ */
+export type NavigationButton = {
+
+    /**
+     * Button icon, defined as a SVG path (see https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#path_commands for more details
+     * on how to define a SVG path).
+     *
+     * The path is rendered within 32 x 32 viewbox (defined as `viewbox="0 0 32 32"`). It must be be a closed path, and must fit within the viewbox incircle.
+     */
+    iconPath: string;
+
+    /**
+     * Human-readable tooltip.
+     */
+    tooltip?: string;
+
+    /**
+     * Whether or not the button is enabled (true by default).
+     */
+    enabled?: boolean;
+
+    /**
+     * Callback invoked when the user clicks on the button.
+     */
+    onClick?: () => void;
+};
+
+
+/**
+ * List of additional buttons to be added to the toolbar of {@link NavigationBoard}, together with optional spacers in-between.
+ */
+export type NavigationButtonList = (NavigationButton | 'spacer')[];
+
+
+/**
+ * Whether the given object is a {@link NavigationButton} or not.
+ */
+export function isNavigationButton(button: unknown): button is NavigationButton {
+    if (typeof button !== 'object' || button === null) {
+        return false;
+    }
+    return typeof (button as NavigationButton).iconPath === 'string' &&
+        ((button as NavigationButton).tooltip === undefined || typeof (button as NavigationButton).tooltip === 'string') &&
+        ((button as NavigationButton).enabled === undefined || typeof (button as NavigationButton).enabled === 'boolean') &&
+        ((button as NavigationButton).onClick === undefined || typeof (button as NavigationButton).onClick === 'function');
+}

package/src/navigationboard/NavigationField.css

@@ -0,0 +1,36 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    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/>.                                         *
+ *                                                                            *
+ * -------------------------------------------------------------------------- */
+
+
+.kokopu-focusFieldContainer {
+    position: fixed;
+    bottom: 0px;
+    right: 0px;
+    width: 0px;
+    height: 0px;
+    overflow: hidden;
+}
+
+.kokopu-focusField {
+    position: absolute; /* see #1 */
+}

package/src/navigationboard/NavigationField.tsx

@@ -0,0 +1,185 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    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 { Game, Variation } from 'kokopu';
+
+import './NavigationField.css';
+
+
+interface NavigationFieldProps {
+    onFirstPressed?: () => void;
+    onPreviousPressed?: () => void;
+    onNextPressed?: () => void;
+    onLastPressed?: () => void;
+    onExitPressed?: () => void;
+}
+
+
+/**
+ * Invisible field, to capture keyboard events.
+ */
+export class NavigationField extends React.Component<NavigationFieldProps> {
+
+    private focusFieldRef: React.RefObject<HTMLAnchorElement> = React.createRef();
+
+    render() {
+        return (
+            <div className="kokopu-focusFieldContainer">
+                <a className="kokopu-focusField" href="#" ref={this.focusFieldRef} onKeyDown={evt => this.handleKeyDown(evt)}></a>
+            </div>
+        );
+    }
+
+    private handleKeyDown(evt: React.KeyboardEvent<HTMLAnchorElement>) {
+        /* eslint-disable no-unused-expressions */
+        doHandleKeyDown(evt, 'Home', this.props.onFirstPressed) ||
+        doHandleKeyDown(evt, 'ArrowLeft', this.props.onPreviousPressed) ||
+        doHandleKeyDown(evt, 'ArrowRight', this.props.onNextPressed) ||
+        doHandleKeyDown(evt, 'End', this.props.onLastPressed) ||
+        doHandleKeyDown(evt, 'Escape', this.props.onExitPressed);
+        /* eslint-enable */
+    }
+
+    /**
+     * Set the focus to the component.
+     */
+    focus(): void {
+        const target = this.focusFieldRef.current;
+        // istanbul ignore else
+        if (target) {
+            target.focus();
+        }
+    }
+
+}
+
+
+function doHandleKeyDown(evt: React.KeyboardEvent<HTMLAnchorElement>, targetKey: string, targetCallback: (() => void) | undefined) {
+
+    // Skip if the pressed key does not match the target key.
+    if (evt.key !== targetKey) {
+        return false;
+    }
+
+    // Otherwise, invoke the callback.
+    if (targetCallback) {
+        evt.preventDefault();
+        targetCallback();
+    }
+    return true;
+}
+
+
+/**
+ * Return the ID of the main variation in the given chess game.
+ * If the given selection corresponds already at the main variation, `undefined` is returned.
+ *
+ * @param game - Considered chess game.
+ * @param selection - ID of the selected move (or `'start'` for the beginning of the main variation).
+ * @public
+ */
+export function firstNodeId(game: Game, selection: string): string | undefined {
+    if (!game.findById(selection)) {
+        return undefined;
+    }
+    return selection === 'start' ? undefined : 'start';
+}
+
+
+/**
+ * Return the ID of the node immediately preceding the given selection in the given chess game.
+ * If no such node exists, `undefined` is returned.
+ *
+ * @param game - Considered chess game.
+ * @param selection - ID of the selected move (or `'start'` for the beginning of the main variation).
+ * @public
+ */
+export function previousNodeId(game: Game, selection: string): string | undefined {
+    let currentNode = game.findById(selection);
+    if (!currentNode) {
+        return undefined;
+    }
+    if (currentNode instanceof Variation) {
+        currentNode = currentNode.parentNode();
+        if (!currentNode) {
+            return undefined; // This case corresponds to the first variation being selected initially.
+        }
+    }
+    while (currentNode) {
+        const previousNode = currentNode.previous();
+        if (previousNode) {
+            return previousNode.id();
+        }
+        currentNode = currentNode.parentVariation().parentNode();
+    }
+    return 'start';
+}
+
+
+/**
+ * Return the ID of the node immediately following the given selection in the given chess game.
+ * If no such node exists, `undefined` is returned.
+ *
+ * @param game - Considered chess game.
+ * @param selection - ID of the selected move (or `'start'` for the beginning of the main variation).
+ * @public
+ */
+export function nextNodeId(game: Game, selection: string): string | undefined {
+    const currentNode = game.findById(selection);
+    if (!currentNode) {
+        return undefined;
+    }
+    const nextNode = currentNode instanceof Variation ? currentNode.first() : currentNode.next();
+    return nextNode ? nextNode.id() : undefined;
+}
+
+
+/**
+ * Return the ID of the node at then end of the variation in which lies the given selection in the given chess game.
+ * If the selection is already at the end its variation, `undefined` is returned.
+ *
+ * @param game - Considered chess game.
+ * @param selection - ID of the selected move (or `'start'` for the beginning of the main variation).
+ * @public
+ */
+export function lastNodeId(game: Game, selection: string): string | undefined {
+    let currentNode = game.findById(selection);
+    if (!currentNode) {
+        return undefined;
+    }
+    currentNode = currentNode instanceof Variation ? currentNode.first() : currentNode.next();
+    if (!currentNode) { // Ensure that the input node is not already the last one.
+        return undefined;
+    }
+    let currentNodeNotNull = currentNode;
+    while (true) {
+        const nextNode = currentNodeNotNull.next();
+        if (!nextNode) {
+            return currentNodeNotNull.id();
+        }
+        currentNodeNotNull = nextNode;
+    }
+}