kokopu-react 1.11.0 → 2.0.0

package/src/movetext/htmlFilter.tsx

@@ -0,0 +1,188 @@
+/* -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    This file is part of Kokopu-React, a JavaScript chess library.          *
+ *    Copyright (C) 2021-2023  Yoann Le Montagner <yo35 -at- melix.net>       *
+ *                                                                            *
+ *    This program 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.                     *
+ *                                                                            *
+ *    This program 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 * as htmlparser2 from 'htmlparser2';
+
+
+/**
+ * Those tags cannot have any children.
+ */
+const NO_CHILDREN_TAGS = new Set([ 'br', 'hr', 'img' ]);
+
+
+/**
+ * For internal use only.
+ */
+type ChildNode = ReturnType<typeof htmlparser2.parseDocument>['children'][0];
+
+
+/**
+ * Instantiate a filter to process the text fields in a {@link Movetext} component.
+ *
+ * @param isComment - Whether the filter is intended to process the comments.
+ */
+export function htmlFilter(type: 'header' | 'comment'): (text: string) => React.ReactNode {
+
+	let allowedTags = [
+		'span', // general purpose
+		'a', // links
+		'b', 'strong', 'i', 'em', // bold, italic
+		'del', 'ins', 's', 'u', // underline, strikethrough
+		'sub', 'sup', // subscript, superscript
+		'abbr', // acronym (typically associated to a title=".." tooltip)
+		'q', 'cite', // quotation and title of a work
+		'mark', // highlighted text
+		'small', // smaller text
+	];
+	const allowedAttributes: Record<string, string[]> = {
+		'*': [ 'class', 'id', 'title' ],
+		'a': [ 'href', 'target' ],
+	};
+
+	if (type === 'comment') {
+		allowedTags = allowedTags.concat([
+			'div', // general purpose
+			'h1', 'h2', 'h3', 'h4', 'h5', 'h6', // headings
+			'p', 'br', // paragraph and line break
+			'blockquote', // long quotation
+			'img', // image
+			'pre', // preformatted text
+			'ul', 'ol', 'li', // lists
+		]);
+		Object.assign(allowedAttributes, {
+			'img': [ 'alt', 'src', 'height', 'width' ],
+		});
+	}
+
+	const sanitizer = new HtmlSanitizer({
+		allowedTags: allowedTags,
+		allowedAttributes: allowedAttributes,
+	});
+	return text => sanitizer.parse(text);
+}
+
+
+interface HtmlSanitizerProps {
+	allowedTags?: string[];
+	allowedAttributes?: Record<string, string[]>;
+}
+
+
+/**
+ * HTML sanitizer: parse HTML string, keeping only the allowed HTML nodes, and the corresponding React object.
+ */
+class HtmlSanitizer {
+
+	#allowedTags: Set<string>;
+	#allowedAttributes: Map<string, Set<string>>;
+	#keyCounter = 0;
+
+	constructor({ allowedTags, allowedAttributes }: HtmlSanitizerProps) {
+		this.#allowedTags = allowedTags ? new Set(allowedTags) : new Set();
+		this.#allowedAttributes = allowedAttributes ? new Map(Object.entries(allowedAttributes).map(([k, v]) => [k, new Set(v)])) : new Map();
+	}
+
+	/**
+	 * @param text - HTML string to be parsed.
+	 * @returns React object corresponding to the given HTML string. Can also be a fragment, or just a simple string if the given HTML string
+	 *          does not contain any HTML tag.
+	 */
+	parse(text: string): React.ReactNode {
+		const dom = htmlparser2.parseDocument(text);
+
+		// Ensure that the returned object is a non-empty node type.
+		if (dom.type !== 'root') {
+			return undefined;
+		}
+
+		// Process the children of the root node.
+		const result: React.ReactNode[] = [];
+		dom.children.forEach(child => {
+			const childElement = this.processNode(child);
+			if (childElement) {
+				result.push(childElement);
+			}
+		});
+
+		// Return the result.
+		if (result.length === 0) {
+			return undefined;
+		}
+		else if (result.length === 1) {
+			return result[0];
+		}
+		else {
+			return <React.Fragment key={this.allocateKey()}>{result}</React.Fragment>;
+		}
+	}
+
+	private processNode(node: ChildNode): React.ReactNode {
+		if (node.type === 'text') {
+			return node.data;
+		}
+		else if (node.type === 'tag') {
+			const children = NO_CHILDREN_TAGS.has(node.name) ? undefined : node.children.map(child => this.processNode(child));
+			if (this.#allowedTags.has(node.name)) {
+				const attributes = this.filterAttributes(node.name, node.attribs);
+				attributes['key'] = this.allocateKey();
+				return React.createElement(node.name, attributes, children);
+			}
+			else {
+				return children ? <React.Fragment key={this.allocateKey()}>{children}</React.Fragment> : undefined;
+			}
+		}
+		else {
+			return undefined;
+		}
+	}
+
+	private filterAttributes(nodeName: string, attributes: Record<string, string>) {
+		const result: Record<string, string> = {};
+		for (const [ attribute, value ] of Object.entries(attributes)) {
+			if (this.isAttributeAllowed(nodeName, attribute)) {
+				result[attribute === 'class' ? 'className' : attribute] = value;
+			}
+		}
+		return result;
+	}
+
+	private isAttributeAllowed(nodeName: string, attribute: string) {
+		if (attribute === 'key' || attribute === 'ref' || attribute === 'className') { // Those attributes are always forbidden.
+			return false;
+		}
+		const allowedAttributesForCurrent = this.#allowedAttributes.get(nodeName);
+		if (allowedAttributesForCurrent && allowedAttributesForCurrent.has(attribute)) {
+			return true;
+		}
+		const allowedAttributesForAll = this.#allowedAttributes.get('*');
+		if (allowedAttributesForAll && allowedAttributesForAll.has(attribute)) {
+			return true;
+		}
+		return false;
+	}
+
+	private allocateKey() {
+		return 'auto-' + (this.#keyCounter++);
+	}
+
+}

package/src/{formatmove.js → movetext/moveFormatter.tsx}

@@ -1,4 +1,4 @@
-/******************************************************************************
+/* -------------------------------------------------------------------------- *
  *                                                                            *
  *    This file is part of Kokopu-React, a JavaScript chess library.          *
  *    Copyright (C) 2021-2023  Yoann Le Montagner <yo35 -at- melix.net>       *
@@ -17,24 +17,26 @@
  *    Public License along with this program. If not, see                     *
  *    <http://www.gnu.org/licenses/>.                                         *
  *                                                                            *
- ******************************************************************************/
+ * -------------------------------------------------------------------------- */
 
 
-import React from 'react';
-import i18n from './i18n';
+import * as React from 'react';
 
-import './css/fonts.css';
+import { IllegalArgument } from '../exception';
+import { i18n } from '../i18n';
+import { PieceSymbolMapping, isPieceSymbolMapping } from '../types';
+
+import './fonts.css';
 
 
 /**
  * Render the given SAN notation according to the given piece symbol style.
  *
- * @param {string|object} pieceSymbols See {@link moveFormatter}.
- * @param {string} notation SAN notation.
- * @returns {string|React.ReactFragment}
+ * @param pieceSymbols - See {@link moveFormatter}.
+ * @param notation - SAN notation.
  */
-export function formatMove(pieceSymbols, notation) {
-	let formatter = moveFormatter(pieceSymbols);
+export function formatMove(pieceSymbols: 'native' | 'localized' | 'figurines' | PieceSymbolMapping, notation: string): React.ReactNode {
+	const formatter = moveFormatter(pieceSymbols);
 	return formatter(notation);
 }
 
@@ -42,45 +44,56 @@ export function formatMove(pieceSymbols, notation) {
 /**
  * Return a callback capable of rendering a SAN notation using the given piece symbol style.
  *
- * @param {string|object} pieceSymbols `'native'`, `'localized'`, `'figurines'`, or an object defining a string-valued properties
- *                                     for each English piece symbol.
- * @returns {function(string)} Callback returning either a string or a React fragment.
+ * @param pieceSymbols - One of the following piece symbol style:
+ *                       - `'native'`: use the English chess piece initials (i.e. K, Q, R, B, N, P).
+ *                       - `'localized'`: use the piece symbols defined in {@link i18n.PIECE_SYMBOLS}.
+ *                       - `'figurines'`: use a figurine font.
+ *                       - {@link PieceSymbolMapping}: use the given custom set of chess piece symbols.
  */
-export function moveFormatter(pieceSymbols) {
-	if (pieceSymbols === 'localized') {
-		let mapping = i18n.PIECE_SYMBOLS;
-		return notation => notation.replace(/[KQRBNP]/g, match => mapping[match]);
+export function moveFormatter(pieceSymbols: 'native' | 'localized' | 'figurines' | PieceSymbolMapping): (notation: string) => React.ReactNode {
+	if (pieceSymbols === 'native') {
+		return notation => notation;
+	}
+	else if (pieceSymbols === 'localized') {
+		const mapping = i18n.PIECE_SYMBOLS;
+		return notation => pieceMappingNotation(mapping, notation);
 	}
 	else if (pieceSymbols === 'figurines') {
 		return notation => figurineNotation('alpha', notation);
 	}
-	else if (pieceSymbols !== 'native' && pieceSymbols && ['K', 'Q', 'R', 'B', 'N', 'P'].every(p => typeof pieceSymbols[p] === 'string')) {
-		return notation => notation.replace(/[KQRBNP]/g, match => pieceSymbols[match]);
+	else if (isPieceSymbolMapping(pieceSymbols)) {
+		return notation => pieceMappingNotation(pieceSymbols, notation);
 	}
 	else {
-		return notation => notation;
+		throw new IllegalArgument('moveFormatter', 'pieceSymbols');
 	}
 }
 
 
+/**
+ * Replace the native piece symbols by those defined by the given {@link PieceSymbolMapping}.
+ */
+function pieceMappingNotation(mapping: PieceSymbolMapping, text: string) {
+	return text.replace(/[KQRBNP]/g, match => mapping[match as keyof PieceSymbolMapping]);
+}
+
+
 /**
  * Decompose the given string into piece symbol characters and sections of non piece symbol characters, and transform the piece symbols into
  * React objects represented with the given chess font.
- *
- * @ignore
  */
-function figurineNotation(fontName, text) {
-	let result = [];
+function figurineNotation(fontName: string, text: string): React.ReactNode {
+	const result: React.ReactNode[] = [];
 	let beginOfText = 0;
 	let pieceSymbolIndex = 0;
 	for (let pos = 0; pos < text.length; ++pos) {
-		let currentChar = text.charAt(pos);
+		const currentChar = text.charAt(pos);
 		if (currentChar === 'K' || currentChar === 'Q' || currentChar === 'R' || currentChar === 'B' || currentChar === 'N' || currentChar === 'P') {
 			if (pos > beginOfText) {
 				result.push(text.substring(beginOfText, pos));
 			}
 			beginOfText = pos + 1;
-			let key = 'symbol-' + (pieceSymbolIndex++);
+			const key = 'symbol-' + (pieceSymbolIndex++);
 			result.push(<span className={'kokopu-font-' + fontName} key={key}>{currentChar}</span>);
 		}
 	}

package/src/sanitization.ts

@@ -0,0 +1,51 @@
+/* -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    This file is part of Kokopu-React, a JavaScript chess library.          *
+ *    Copyright (C) 2021-2023  Yoann Le Montagner <yo35 -at- melix.net>       *
+ *                                                                            *
+ *    This program 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.                     *
+ *                                                                            *
+ *    This program 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 { IllegalArgument } from './exception';
+
+
+export function sanitizeString(input: string): string {
+	return String(input);
+}
+
+
+export function sanitizeBoolean(input: boolean): boolean {
+	return Boolean(input);
+}
+
+
+export function sanitizeInteger(input: number, exceptionBuilder: () => IllegalArgument): number {
+	if (typeof input !== 'number' || !Number.isFinite(input)) {
+		throw exceptionBuilder();
+	}
+	return Math.round(input);
+}
+
+
+export function sanitizeBoundedInteger(input: number, min: number, max: number, exceptionBuilder: () => IllegalArgument) {
+	return Math.min(Math.max(sanitizeInteger(input, exceptionBuilder), min), max);
+}
+
+
+export function sanitizeOptional<T>(input: T | undefined, sanitizationFunction: (val: T) => T): T | undefined {
+	return input === undefined || input === null ? undefined : sanitizationFunction(input);
+}

package/src/types.ts

@@ -0,0 +1,311 @@
+/* -------------------------------------------------------------------------- *
+ *                                                                            *
+ *    This file is part of Kokopu-React, a JavaScript chess library.          *
+ *    Copyright (C) 2021-2023  Yoann Le Montagner <yo35 -at- melix.net>       *
+ *                                                                            *
+ *    This program 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.                     *
+ *                                                                            *
+ *    This program 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 { Square, SquareCouple, isSquare, isSquareCouple } from 'kokopu';
+
+import { IllegalArgument } from './exception';
+
+
+/**
+ * Minimum square size in a {@link Chessboard} component.
+ */
+export const MIN_SQUARE_SIZE = 12;
+
+/**
+ * Maximum square size in a {@link Chessboard} component.
+ */
+export const MAX_SQUARE_SIZE = 96;
+
+
+/**
+ * Set of parameters describing the colors to use to render a {@link Chessboard} component.
+ *
+ * Each color is defined as string, that must be interpreted as a [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ */
+export type Colorset = {
+
+	/** Color of the black squares. */
+	b: string;
+
+	/** Color of the white squares. */
+	w: string;
+
+	/** Color of the blue markers. */
+	cb: string;
+
+	/** Color of the green markers. */
+	cg: string;
+
+	/** Color of the red markers. */
+	cr: string;
+
+	/** Color of the yellow markers. */
+	cy: string;
+};
+
+
+/**
+ * Set of parameters describing the chess pieces to use to render a {@link Chessboard} component.
+ *
+ * Each field is a string corresponding to the URL of the image of the corresponding chess piece.
+ */
+export type Pieceset = {
+
+	/** Image for the black bishops. */
+	bb: string;
+
+	/** Image for the black kings. */
+	bk: string;
+
+	/** Image for the black knights. */
+	bn: string;
+
+	/** Image for the black pawns. */
+	bp: string;
+
+	/** Image for the black queens. */
+	bq: string;
+
+	/** Image for the black rooks. */
+	br: string;
+
+	/** Image for the black turn flags. */
+	bx: string;
+
+	/** Image for the white bishops. */
+	wb: string;
+
+	/** Image for the white kings. */
+	wk: string;
+
+	/** Image for the white knights. */
+	wn: string;
+
+	/** Image for the white pawns. */
+	wp: string;
+
+	/** Image for the white queens. */
+	wq: string;
+
+	/** Image for the white rooks. */
+	wr: string;
+
+	/** Image for the white turn flags. */
+	wx: string;
+};
+
+
+/**
+ * Set of aliases for chess pieces symbols.
+ */
+export type PieceSymbolMapping = {
+	K: string;
+	Q: string;
+	R: string;
+	B: string;
+	N: string;
+	P: string;
+};
+
+
+/**
+ * Whether the given object is a {@link PieceSymbolMapping} or not.
+ */
+export function isPieceSymbolMapping(mapping: unknown): mapping is PieceSymbolMapping {
+	if (typeof mapping !== 'object' || mapping === null) {
+		return false;
+	}
+	return typeof (mapping as PieceSymbolMapping).K === 'string' &&
+		typeof (mapping as PieceSymbolMapping).Q === 'string' &&
+		typeof (mapping as PieceSymbolMapping).R === 'string' &&
+		typeof (mapping as PieceSymbolMapping).B === 'string' &&
+		typeof (mapping as PieceSymbolMapping).N === 'string' &&
+		typeof (mapping as PieceSymbolMapping).P === 'string';
+}
+
+
+/**
+ * Symbol that can be chosen to decorate a square in a {@link Chessboard}.
+ */
+export type AnnotationSymbol = 'plus' | 'times' | 'dot' | 'circle' |
+	'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' |
+	'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' |
+	'0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+
+
+/**
+ * Whether the given object is a {@link AnnotationSymbol} or not.
+ */
+export function isAnnotationSymbol(symbol: unknown): symbol is AnnotationSymbol {
+	return typeof symbol === 'string' && /^(?:[A-Za-z0-9]|plus|times|dot|circle)$/.test(symbol);
+}
+
+
+/**
+ * Color that can be chosen to decorate a square or draw an arrow in a {@link Chessboard}.
+ */
+export type AnnotationColor = 'b' | 'g' | 'r' | 'y';
+
+
+/**
+ * Whether the given object is a {@link AnnotationSymbol} or not.
+ */
+export function isAnnotationColor(color: unknown): color is AnnotationColor {
+	return color === 'b' || color === 'g' || color === 'r' || color === 'y';
+}
+
+
+/**
+ * Set of square markers (i.e. colorized squares in a {@link Chessboard}).
+ */
+export type SquareMarkerSet = Partial<Record<Square, AnnotationColor>>;
+
+
+/**
+ * Set of text markers (i.e. colorized symbols that can decorate the squares of a {@link Chessboard}).
+ */
+export type TextMarkerSet = Partial<Record<Square, { symbol: AnnotationSymbol, color: AnnotationColor }>>;
+
+
+/**
+ * Set of arrow markers (i.e. colorized arrows between two squares in a {@link Chessboard}).
+ */
+export type ArrowMarkerSet = Partial<Record<SquareCouple, AnnotationColor>>;
+
+
+/**
+ * Transform a {@link SquareMarkerSet} into a comma-separated string.
+ *
+ * @param markers - For example: `{ e4: 'g', d5: 'r' }`
+ * @returns For example: `'Gd5,Ge4'`
+ */
+export function flattenSquareMarkers(markers: SquareMarkerSet): string {
+	if (typeof markers !== 'object' || markers === null) {
+		throw new IllegalArgument('flattenSquareMarkers()', 'markers');
+	}
+	return Object.entries(markers)
+		.filter(([ sq, color ]) => isSquare(sq) && isAnnotationColor(color))
+		.sort((a, b) => a[0].localeCompare(b[0]))
+		.map(([ sq, color ]) => color.toUpperCase() + sq)
+		.join(',');
+}
+
+
+/**
+ * Transform a {@link TextMarkerSet} into a comma-separated string.
+ *
+ * @param markers - For example: `{ e4: { symbol: 'A', color: 'g' }, d5: { symbol: 'z', color: 'r' }, h3: { symbol: 'plus', color: 'y' } }`
+ * @returns For example: `'Rzd5,GAe4,Y(plus)h3'`
+ */
+export function flattenTextMarkers(markers: TextMarkerSet): string {
+	if (typeof markers !== 'object' || markers === null) {
+		throw new IllegalArgument('flattenTextMarkers()', 'markers');
+	}
+	return Object.entries(markers)
+		.filter(([ sq, desc ]) => isSquare(sq) && desc && isAnnotationColor(desc.color) && isAnnotationSymbol(desc.symbol))
+		.sort((a, b) => a[0].localeCompare(b[0]))
+		.map(([ sq, desc ]) => desc.color.toUpperCase() + (desc.symbol.length === 1 ? desc.symbol : `(${desc.symbol})`) + sq)
+		.join(',');
+}
+
+
+/**
+ * Transform a {@link ArrowMarkerSet} into a comma-separated string.
+ *
+ * @param markers - For example: `{ e2e4: 'g', g8f6: 'r', g8h6: 'b' }`
+ * @returns For example: `'Ge2e4,Rg8f6,Bg8h6'`
+ */
+export function flattenArrowMarkers(markers: ArrowMarkerSet): string {
+	if (typeof markers !== 'object' || markers === null) {
+		throw new IllegalArgument('flattenArrowMarkers()', 'markers');
+	}
+	return Object.entries(markers)
+		.filter(([ vect, color ]) => isSquareCouple(vect) && isAnnotationColor(color))
+		.sort((a, b) => a[0].localeCompare(b[0]))
+		.map(([ vect, color ]) => color.toUpperCase() + vect)
+		.join(',');
+}
+
+
+/**
+ * Parse a comma-separated string representing a {@link SquareMarkerSet}.
+ *
+ * @param markers - For example: `'Gd5,Ge4'`
+ * @returns For example: `{ e4: 'g', d5: 'r' }`
+ */
+export function parseSquareMarkers(markers: string): SquareMarkerSet {
+	if (typeof markers !== 'string') {
+		throw new IllegalArgument('parseSquareMarkers()', 'markers');
+	}
+	return parseMarkers<Square, AnnotationColor>(markers, token => {
+		return /^([BGRY])([a-h][1-8])$/.test(token) ?
+			{ key: RegExp.$2 as Square, value: RegExp.$1.toLowerCase() as AnnotationColor } :
+			undefined;
+	});
+}
+
+
+/**
+ * Parse a comma-separated string representing a {@link TextMarkerSet}.
+ *
+ * @param markers - For example: `'Rzd5,GAe4,Y(plus)h3'`
+ * @returns For example: `{ e4: { symbol: 'A', color: 'g' }, d5: { symbol: 'z', color: 'r' }, h3: { symbol: 'plus', color: 'y' } }`
+ */
+export function parseTextMarkers(markers: string): TextMarkerSet {
+	if (typeof markers !== 'string') {
+		throw new IllegalArgument('parseTextMarkers()', 'markers');
+	}
+	return parseMarkers<Square, { symbol: AnnotationSymbol, color: AnnotationColor }>(markers, token => {
+		return /^([BGRY])(?:([A-Za-z0-9])|\((plus|times|dot|circle)\))([a-h][1-8])$/.test(token) ?
+			{ key: RegExp.$4 as Square, value: { symbol: (RegExp.$2 || RegExp.$3) as AnnotationSymbol, color: RegExp.$1.toLowerCase() as AnnotationColor } } :
+			undefined;
+	});
+}
+
+
+/**
+ * Parse a comma-separated string representing a {@link ArrowMarkerSet}.
+ *
+ * @param markers - For example: `'Ge2e4,Rg8f6,Bg8h6'`
+ * @returns For example: `{ e2e4: 'g', g8f6: 'r', g8h6: 'b' }`
+ */
+export function parseArrowMarkers(markers: string): ArrowMarkerSet {
+	if (typeof markers !== 'string') {
+		throw new IllegalArgument('parseArrowMarkers()', 'markers');
+	}
+	return parseMarkers<SquareCouple, AnnotationColor>(markers, token => {
+		return /^([BGRY])([a-h][1-8][a-h][1-8])$/.test(token) ?
+			{ key: RegExp.$2 as SquareCouple, value: RegExp.$1.toLowerCase() as AnnotationColor } :
+			undefined;
+	});
+}
+
+
+function parseMarkers<K extends string, V>(markers: string, tokenParser: (token: string) => { key: K, value: V } | undefined): Partial<Record<K, V>> {
+	const result: Partial<Record<K, V>> = {};
+	markers.split(',').map(token => tokenParser(token.trim())).forEach(marker => {
+		if (marker) {
+			result[marker.key] = marker.value;
+		}
+	});
+	return result;
+}