kokopu-react 3.1.0 → 3.3.0

package/src/navigationboard/NavigationButton.ts

@@ -0,0 +1,114 @@
+/*!
+ * -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    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 NavigationBar = (NavigationButton | 'spacer')[];
+
+
+/**
+ * Scheme of additional button list to be added to the toolbar of {@link NavigationBoard}, together with optional spacers in-between.
+ */
+export type NavigationBarScheme = ('button' | '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');
+}
+
+
+/**
+ * Whether the given object is a {@link NavigationBar} or not.
+ */
+export function isNavigationBar(buttons: unknown): buttons is NavigationBar {
+    if (Array.isArray(buttons)) {
+        for (const button of buttons) {
+            if (!(isNavigationButton(button) || button === 'spacer')) {
+                return false;
+            }
+        }
+        return true;
+    }
+    else {
+        return false;
+    }
+}
+
+
+/**
+ * Whether the given object is a {@link NavigationBarScheme} or not.
+ */
+export function isNavigationBarScheme(buttons: unknown): buttons is NavigationBarScheme {
+    if (Array.isArray(buttons)) {
+        for (const button of buttons) {
+            if (!(button === 'button' || button === 'spacer')) {
+                return false;
+            }
+        }
+        return true;
+    }
+    else {
+        return false;
+    }
+}

package/src/navigationboard/NavigationField.css

@@ -23,14 +23,14 @@
 
 
 .kokopu-focusFieldContainer {
-	position: fixed;
-	bottom: 0px;
-	right: 0px;
-	width: 0px;
-	height: 0px;
-	overflow: hidden;
+    position: fixed;
+    bottom: 0px;
+    right: 0px;
+    width: 0px;
+    height: 0px;
+    overflow: hidden;
 }
 
 .kokopu-focusField {
-	position: absolute; /* see #1 */
+    position: absolute; /* see #1 */
 }

package/src/navigationboard/NavigationField.tsx

@@ -30,11 +30,11 @@ import './NavigationField.css';
 
 
 interface NavigationFieldProps {
-	onFirstPressed?: () => void;
-	onPreviousPressed?: () => void;
-	onNextPressed?: () => void;
-	onLastPressed?: () => void;
-	onExitPressed?: () => void;
+    onFirstPressed?: () => void;
+    onPreviousPressed?: () => void;
+    onNextPressed?: () => void;
+    onLastPressed?: () => void;
+    onExitPressed?: () => void;
 }
 
 
@@ -43,53 +43,53 @@ interface NavigationFieldProps {
  */
 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();
-		}
-	}
+    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;
+    // 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;
 }
 
 
@@ -102,10 +102,10 @@ function doHandleKeyDown(evt: React.KeyboardEvent<HTMLAnchorElement>, targetKey:
  * @public
  */
 export function firstNodeId(game: Game, selection: string): string | undefined {
-	if (!game.findById(selection)) {
-		return undefined;
-	}
-	return selection === 'start' ? undefined : 'start';
+    if (!game.findById(selection)) {
+        return undefined;
+    }
+    return selection === 'start' ? undefined : 'start';
 }
 
 
@@ -118,24 +118,24 @@ export function firstNodeId(game: Game, selection: string): string | undefined {
  * @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';
+    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';
 }
 
 
@@ -148,12 +148,12 @@ export function previousNodeId(game: Game, selection: string): string | undefine
  * @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;
+    const currentNode = game.findById(selection);
+    if (!currentNode) {
+        return undefined;
+    }
+    const nextNode = currentNode instanceof Variation ? currentNode.first() : currentNode.next();
+    return nextNode ? nextNode.id() : undefined;
 }
 
 
@@ -166,20 +166,20 @@ export function nextNodeId(game: Game, selection: string): string | undefined {
  * @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;
-	}
+    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;
+    }
 }

package/src/navigationboard/NavigationToolbar.css

@@ -23,29 +23,32 @@
 
 
 .kokopu-navigationBoard {
-	display: flex;
-	flex-direction: column;
-	align-items: center;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
 }
 
 .kokopu-navigationToolbar {
-	line-height: 0px;
+    line-height: 0px;
 }
 
-.kokopu-navigationButton {
-	display: inline-block;
-	cursor: pointer;
+.kokopu-enabledNavigationButton,
+.kokopu-disabledNavigationButton {
+    display: inline-block;
 }
 
-.kokopu-navigationButton:hover {
-	opacity: 0.6;
+.kokopu-enabledNavigationButton {
+    cursor: pointer;
 }
 
-* + .kokopu-navigationButton {
-	margin-left: 2px;
+.kokopu-enabledNavigationButton:hover {
+    opacity: 0.6;
+}
+
+.kokopu-disabledNavigationButton {
+    opacity: 0.2;
 }
 
 .kokopu-navigationSpacer {
-	display: inline-block;
-	width: 10px;
+    display: inline-block;
 }

package/src/navigationboard/NavigationToolbar.tsx

@@ -22,153 +22,139 @@
  * -------------------------------------------------------------------------- */
 
 
-
 import * as React from 'react';
 
-import { i18n } from '../i18n';
+import { NavigationButton, NavigationBar, NavigationBarScheme } from './NavigationButton';
 
 import './NavigationToolbar.css';
 
-const THICKNESS = 2;
-const CHEVRON_SIZE = 7;
-const ARROW_SIZE = 5;
-const ARROW_LENGTH = 16;
-
 
 interface NavigationToolbarProps {
-	flipButtonVisible: boolean;
-	squareSize: number;
-	onFirstClicked?: () => void;
-	onPreviousClicked?: () => void;
-	onNextClicked?: () => void;
-	onLastClicked?: () => void;
-	onFlipClicked?: () => void;
+    squareSize: number;
+    buttons: NavigationBar;
 }
 
 
 /**
  * Toolbar below the navigation board.
  */
-export class NavigationToolbar extends React.Component<NavigationToolbarProps> {
-
-	render() {
-		const buttonSize = computeButtonSize(this.props.squareSize);
-		const marginTop = Math.round(buttonSize / 4);
-		return (
-			<div className="kokopu-navigationToolbar" style={{ marginTop: marginTop }}>
-				<NavigationButton size={buttonSize} tooltip={i18n.TOOLTIP_GO_FIRST} path={chevronPath(14, 16, -1) + ' ' + chevronPath(10, 16, -1)}
-					onClick={this.props.onFirstClicked} />
-				<NavigationButton size={buttonSize} tooltip={i18n.TOOLTIP_GO_PREVIOUS} path={chevronPath(12, 16, -1)}
-					onClick={this.props.onPreviousClicked} />
-				<NavigationButton size={buttonSize} tooltip={i18n.TOOLTIP_GO_NEXT} path={chevronPath(20, 16, 1)}
-					onClick={this.props.onNextClicked} />
-				<NavigationButton size={buttonSize} tooltip={i18n.TOOLTIP_GO_LAST} path={chevronPath(18, 16, 1) + ' ' + chevronPath(22, 16, 1)}
-					onClick={this.props.onLastClicked} />
-				{this.renderFlipButton(buttonSize)}
-			</div>
-		);
-	}
-
-	private renderFlipButton(buttonSize: number) {
-		if (!this.props.flipButtonVisible) {
-			return undefined;
-		}
-		return (<>
-			<div className="kokopu-navigationSpacer" />
-			<NavigationButton size={buttonSize} tooltip={i18n.TOOLTIP_FLIP} path={arrowPath(11, 25, 1) + ' ' + arrowPath(21, 7, -1)}
-				onClick={this.props.onFlipClicked} />
-		</>);
-	}
-
+export function NavigationToolbar({ squareSize, buttons }: NavigationToolbarProps) {
+
+    const buttonSize = computeButtonSize(squareSize);
+    const spacerSize = computeSpacerSize(squareSize);
+    const buttonNodes: React.ReactNode[] = [];
+
+    let atLeastOneButtonEncountered = false;
+    for (let i = 0; i < buttons.length; ++i) {
+
+        const button = buttons[i];
+
+        // Skip the spacers.
+        if (button === 'spacer') {
+            continue;
+        }
+
+        // Enqueue a spacer if necessary.
+        // Remark: consecutive spacers are collapsed into a single one for rendering, and spacers at the begin and end of the button list are not rendered.
+        if (atLeastOneButtonEncountered && buttons[i - 1] === 'spacer') {
+            buttonNodes.push(<div key={buttonNodes.length} className="kokopu-navigationSpacer" style={{ width: spacerSize }} />);
+        }
+        atLeastOneButtonEncountered = true;
+
+        // Enqueue the button node.
+        buttonNodes.push(<NavigationButtonImpl
+            key={buttonNodes.length}
+            tooltip={button.tooltip} iconPath={button.iconPath} enabled={button.enabled} onClick={button.onClick}
+            size={buttonSize}
+            spaceOnLeft={i === 0 || buttons[i - 1] === 'spacer'}
+            spaceOnRight={i === buttons.length - 1 || buttons[i + 1] === 'spacer'}
+        />);
+    }
+
+    return <div className="kokopu-navigationToolbar" style={{ marginTop: computeMarginTop(squareSize) }}>{buttonNodes}</div>;
 }
 
 
-interface NavigationButtonProps {
-	size: number;
-	tooltip: string;
-	path: string;
-	onClick?: () => void;
+interface NavigationButtonImplProps extends NavigationButton {
+    size: number;
+    spaceOnLeft: boolean;
+    spaceOnRight: boolean;
 }
 
 
 /**
  * Button for the navigation toolbar.
  */
-function NavigationButton({ size, tooltip, path, onClick }: NavigationButtonProps) {
-	return (
-		<div className="kokopu-navigationButton" title={tooltip} onClick={onClick}>
-			<svg viewBox="0 0 32 32" width={size} height={size}>
-				<path d={`M 16 0 A 16 16 0 0 0 16 32 A 16 16 0 0 0 16 0 Z ${path}`} fill="currentcolor" />
-			</svg>
-		</div>
-	);
+function NavigationButtonImpl({ size, spaceOnLeft, spaceOnRight, iconPath, tooltip, enabled, onClick }: NavigationButtonImplProps) {
+    const leftBoundary = spaceOnLeft ? 'A 16 16 0 0 0 16 32' : 'L 1 0 L 1 32 L 16 32';
+    const rightBoundary = spaceOnRight ? 'A 16 16 0 0 0 16 0' : 'L 31 32 L 31 0 L 16 0';
+    const actuallyEnabled = enabled ?? true;
+    return (
+        <div className={actuallyEnabled ? 'kokopu-enabledNavigationButton' : 'kokopu-disabledNavigationButton'} title={tooltip}
+            onClick={actuallyEnabled ? onClick : undefined}
+        >
+            <svg viewBox="0 0 32 32" width={size} height={size}>
+                <path d={`M 16 0 ${leftBoundary} ${rightBoundary} Z ${iconPath}`} fill="currentcolor" />
+            </svg>
+        </div>
+    );
 }
 
 
 /**
- *      * C
- *     / \
- *  B *   \
- *     \   \
- *      \   \
- *     A *   * D
- *      /   /
- *     /   /
- *  F *   /
- *     \ /
- *      * E
- *
- * (x,y) = middle of [AD]
+ * Size of the navigation toolbar (taking into account the margin between the toolbar and the chessboard), assuming the given square size.
  */
-function chevronPath(x: number, y: number, direction: 1 | -1) {
-	const xA = x - direction * THICKNESS * Math.sqrt(2) / 2;
-	const xB = x - direction * (CHEVRON_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const xC = x - direction * (CHEVRON_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	const xD = x + direction * THICKNESS * Math.sqrt(2) / 2;
-	const yB = y - direction * (CHEVRON_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	const yC = y - direction * (CHEVRON_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const yE = y + direction * (CHEVRON_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const yF = y + direction * (CHEVRON_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	return `M ${xA} ${y} L ${xB} ${yB} L ${xC} ${yC} L ${xD} ${y} L ${xC} ${yE} L ${xB} ${yF} Z`;
+export function navigationToolbarSize(squareSize: number, buttons: NavigationBarScheme): { width: number, height: number } {
+
+    const buttonSize = computeButtonSize(squareSize);
+    const spacerSize = computeSpacerSize(squareSize);
+    let width = 0;
+
+    let atLeastOneButtonEncountered = false;
+    for (let i = 0; i < buttons.length; ++i) {
+
+        // Skip the spacers.
+        if (buttons[i] === 'spacer') {
+            continue;
+        }
+
+        // Enqueue a spacer if necessary.
+        // Remark: consecutive spacers are collapsed into a single one for rendering, and spacers at the begin and end of the button list are not rendered.
+        if (atLeastOneButtonEncountered && buttons[i - 1] === 'spacer') {
+            width += spacerSize;
+        }
+        atLeastOneButtonEncountered = true;
+
+        // Enqueue the button node.
+        width += buttonSize;
+    }
+
+    return {
+        width: width,
+        height: buttonSize + computeMarginTop(squareSize),
+    };
 }
 
 
 /**
- *      D +---+ E
- *        |   |
- *        |   |
- *        |   |
- *   B *  |   |  * G
- *    / \ |   | / \
- * A *   \|   |/   * H
- *    \   *   *   /
- *     \  C   F  /
- *      \   O   /
- *       \  *  /
- *        \   /
- *         \ /
- *          *
- *        (x,y)
+ * Return the height/width of the buttons assuming the given square size.
  */
-function arrowPath(x: number, y: number, direction: 1 | -1) {
-	const xA = x - direction * (ARROW_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const xB = x - direction * (ARROW_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	const xC = x - direction * THICKNESS / 2;
-	const xF = x + direction * THICKNESS / 2;
-	const xG = x + direction * (ARROW_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	const xH = x + direction * (ARROW_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const y0 = y - direction * THICKNESS * Math.sqrt(2) / 2;
-	const yA = y0 - direction * (ARROW_SIZE - THICKNESS / Math.sqrt(2) / 2);
-	const yB = y0 - direction * (ARROW_SIZE + THICKNESS / Math.sqrt(2) / 2);
-	const yC = yB + (xC - xB);
-	const yD = y - direction * ARROW_LENGTH;
-	return `M ${x} ${y} L ${xA} ${yA} L ${xB} ${yB} L ${xC} ${yC} V ${yD} H ${xF} V ${yC} L ${xG} ${yB} L ${xH} ${yA} Z`;
+function computeButtonSize(squareSize: number) {
+    return Math.round((squareSize * 2 + 116) / 7);
 }
 
 
 /**
- * Return the height/width of the buttons assuming the given square size.
+ * Return the width of the spacer between button groups, assuming the given square size.
  */
-function computeButtonSize(squareSize: number) {
-	return Math.round((squareSize * 2 + 116) / 7);
+function computeSpacerSize(squareSize: number) {
+    return Math.round((squareSize * 2 + 116) / 14);
+}
+
+
+/**
+ * Return the height of the margin between the toolbar and the chessboard.
+ */
+function computeMarginTop(squareSize: number) {
+    return Math.round((squareSize * 2 + 116) / 28);
 }