npm - cm-chessboard - Versions diffs - 8.12.18 → 8.13.0 - Mend

cm-chessboard 8.12.18 → 8.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +6 -0
package/examples/extensions/piece-rotation-extension.html +53 -0
package/package.json +1 -1
package/src/Chessboard.js +8 -0
package/src/extensions/piece-rotation/PieceRotation.js +171 -0
package/src/extensions/piece-rotation/README.md +39 -0
package/src/view/VisualMoveInput.js +38 -1
package/test/TestPieceRotation.js +138 -0
package/test/TestVisualMoveInput.js +127 -0
package/test/index.html +2 -0

package/README.md CHANGED Viewed

@@ -247,6 +247,12 @@ chessboard.enableMoveInput((event) => {
 Disables moves via user input.
+### cancelMoveInput()
+Cancels a move input that is currently in progress (a piece picked up or a square selected), without disabling move
+input. Fires a `moveInputCanceled` event with `event.reason === "canceled"`. It is a no-op when no move input is in
+progress. Useful to abort a move from your own UI, e.g. on an "escape" key press or a cancel button.
 ### isMoveInputEnabled()
 Returns `true` if move input is currently enabled for white or black.

package/examples/extensions/piece-rotation-extension.html ADDED Viewed

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>cm-chessboard</title>
+    <meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0"/>
+    <link rel="stylesheet" href="../styles/examples.css"/>
+    <link rel="stylesheet" href="../../assets/chessboard.css"/>
+</head>
+<body>
+<h1><a href="../../">cm-chessboard</a></h1>
+<h2>Example: PieceRotation Extension</h2>
+<p>Rotates the piece glyphs in place, by any angle, optionally animated — either all pieces or only those
+    of one color. Useful for over-the-board play on a tablet lying flat between two players. Moving pieces
+    stays enabled, the rotation survives moves and position changes.</p>
+<div class="board" id="board"></div>
+<div style="clear: both"></div>
+<p>
+    <select id="color">
+        <option value="">all pieces</option>
+        <option value="w">white only</option>
+        <option value="b">black only</option>
+    </select>
+    <button onclick="window.rotate(0)">0&deg;</button>
+    <button onclick="window.rotate(90)">90&deg;</button>
+    <button onclick="window.rotate(180)">180&deg;</button>
+    <button onclick="window.rotate(270)">270&deg;</button>
+    <label><input type="checkbox" id="animated" checked> animated</label>
+</p>
+<script type="module">
+    import {Chessboard} from "../../src/Chessboard.js"
+    import {FEN} from "../../src/model/Position.js"
+    import {PieceRotation} from "../../src/extensions/piece-rotation/PieceRotation.js"
+    const board = new Chessboard(document.getElementById("board"), {
+        position: FEN.start,
+        assetsCache: false,
+        assetsUrl: "../../assets/",
+        style: {aspectRatio: 0.98},
+        extensions: [{class: PieceRotation}]
+    })
+    board.enableMoveInput(() => {
+        return true // allow all moves in this demo
+    })
+    window.rotate = (angle) => {
+        board.setPiecesRotation(angle, {
+            color: document.getElementById("color").value || undefined,
+            animated: document.getElementById("animated").checked
+        })
+    }
+</script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "cm-chessboard",
-  "version": "8.12.18",
+  "version": "8.13.0",
   "description": "A JavaScript chessboard which is lightweight, ES6 module based, responsive, SVG rendered and without dependencies.",
   "keywords": [
     "chess",

package/src/Chessboard.js CHANGED Viewed

@@ -77,6 +77,7 @@ export class Chessboard {
     async setPiece(square, piece, animated = false) {
         const positionFrom = this.state.position.clone()
         this.state.position.setPiece(square, piece)
+        this.view.visualMoveInput.positionChanged()
         this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
     }
@@ -84,6 +85,7 @@ export class Chessboard {
     async movePiece(squareFrom, squareTo, animated = false) {
         const positionFrom = this.state.position.clone()
         this.state.position.movePiece(squareFrom, squareTo)
+        this.view.visualMoveInput.positionChanged()
         this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
     }
@@ -93,6 +95,7 @@ export class Chessboard {
         const positionTo = new Position(fen)
         if (positionFrom.getFen() !== positionTo.getFen()) {
             this.state.position.setFen(fen)
+            this.view.visualMoveInput.positionChanged()
             this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         }
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
@@ -131,6 +134,11 @@ export class Chessboard {
         this.view.disableMoveInput()
     }
+    // Cancel a move input that is currently in progress (leaves move input enabled).
+    cancelMoveInput() {
+        this.view.visualMoveInput.cancelMoveInput()
+    }
     isMoveInputEnabled() {
         return this.state.inputWhiteEnabled || this.state.inputBlackEnabled
     }

package/src/extensions/piece-rotation/PieceRotation.js ADDED Viewed

@@ -0,0 +1,171 @@
+/**
+ * Author and copyright: Stefan Haack (https://shaack.com)
+ * Repository: https://github.com/shaack/cm-chessboard
+ * License: MIT, see file 'LICENSE'
+ */
+import {Extension, EXTENSION_POINT} from "../../model/Extension.js"
+import {COLOR} from "../../Chessboard.js"
+/**
+ * Rotates the piece glyphs in place, by any angle, optionally animated —
+ * either all pieces or only those of one color. The squares and the position
+ * stay untouched, only the glyphs turn around their own center. Useful for
+ * over-the-board play on a tablet lying flat between two players: rotate the
+ * pieces by 180 degrees towards the player to move.
+ *
+ * The rotation is implemented as an additional SVGTransform appended to each
+ * piece's `use` element, after the translate and scale the view sets there.
+ * Appended last, it rotates in sprite coordinates around the tile center, so
+ * it composes with any piece position and survives the move animations, which
+ * only touch the translate of the surrounding group. A MutationObserver
+ * re-applies the angles to freshly drawn pieces, so the rotation survives
+ * redraws and position changes from any code path.
+ *
+ * Registers two methods on the chessboard:
+ *
+ *   // rotate all pieces, animated
+ *   chessboard.setPiecesRotation(180)
+ *   // rotate only the black pieces, not animated
+ *   chessboard.setPiecesRotation(180, {color: COLOR.black, animated: false})
+ *   // returns a Promise, resolved when the rotation is shown
+ *   await chessboard.setPiecesRotation(0)
+ *
+ *   chessboard.getPiecesRotation(COLOR.white) // current target angle
+ */
+export class PieceRotation extends Extension {
+    constructor(chessboard, props = {}) {
+        super(chessboard)
+        this.props = {
+            angle: 0, // the initial rotation angle in degrees, for all pieces
+            animationDuration: 300 // duration of an animated rotation in milliseconds
+        }
+        Object.assign(this.props, props)
+        this.angles = {w: this.props.angle, b: this.props.angle}
+        this.targetAngles = {w: this.props.angle, b: this.props.angle}
+        this.animations = {w: null, b: null}
+        // Redraws and animations replace the piece elements with fresh ones
+        // without the rotation, and they do so from several code paths — some
+        // of them after all extension points have fired (redrawPieces runs in
+        // the animation queue's callback). A MutationObserver on the pieces
+        // group catches every new element, no matter which path created it.
+        this.observer = new MutationObserver(() => {
+            this.applyAngles()
+        })
+        this.observer.observe(chessboard.view.piecesGroup, {childList: true, subtree: true})
+        this.registerExtensionPoint(EXTENSION_POINT.destroy, () => {
+            this.observer.disconnect()
+            this.cancelAnimation(COLOR.white)
+            this.cancelAnimation(COLOR.black)
+        })
+        chessboard.setPiecesRotation = this.setPiecesRotation.bind(this)
+        chessboard.getPiecesRotation = this.getPiecesRotation.bind(this)
+        if (this.props.angle !== 0) {
+            this.applyAngles()
+        }
+    }
+    /**
+     * Rotate pieces to `angle` degrees. Returns a Promise which resolves when
+     * the rotation is shown, after the animation if animated.
+     *
+     * @param angle target angle in degrees
+     * @param props {color: COLOR.white|COLOR.black|undefined, animated: true}
+     *              without `color` all pieces are rotated
+     */
+    setPiecesRotation(angle, props = {}) {
+        const {color = undefined, animated = true} = props
+        const colors = color ? [color] : [COLOR.white, COLOR.black]
+        const promises = colors.map((rotatedColor) => this.rotateColor(rotatedColor, angle, animated))
+        return Promise.all(promises)
+    }
+    /**
+     * The current target angle of a color's pieces.
+     */
+    getPiecesRotation(color = COLOR.white) {
+        return this.targetAngles[color]
+    }
+    // -- internal ------------------------------------------------------------
+    rotateColor(color, angle, animated) {
+        this.targetAngles[color] = angle
+        this.cancelAnimation(color)
+        if (!animated || this.props.animationDuration <= 0 || angle === this.angles[color]) {
+            this.angles[color] = angle
+            this.applyAngles()
+            return Promise.resolve()
+        }
+        return new Promise((resolve) => {
+            const startAngle = this.angles[color]
+            let startTime = null
+            const animation = {resolve}
+            const step = (time) => {
+                if (!this.chessboard.state) { // board was destroyed
+                    return
+                }
+                if (startTime === null) {
+                    startTime = time
+                }
+                const t = Math.min(1, (time - startTime) / this.props.animationDuration)
+                const progress = t < .5 ? 2 * t * t : -1 + (4 - 2 * t) * t // easeInOut
+                this.angles[color] = startAngle + (angle - startAngle) * progress
+                this.applyAngles()
+                if (t < 1) {
+                    animation.frameHandle = requestAnimationFrame(step)
+                } else {
+                    this.animations[color] = null
+                    resolve()
+                }
+            }
+            animation.frameHandle = requestAnimationFrame(step)
+            this.animations[color] = animation
+        })
+    }
+    /**
+     * A superseded animation stops where it is, its promise resolves. The new
+     * rotation starts from the currently shown angle.
+     */
+    cancelAnimation(color) {
+        const animation = this.animations[color]
+        if (animation) {
+            cancelAnimationFrame(animation.frameHandle)
+            animation.resolve()
+            this.animations[color] = null
+        }
+    }
+    applyAngles() {
+        const center = this.chessboard.props.style.pieces.tileSize / 2
+        const groups = this.chessboard.view.piecesGroup.querySelectorAll("g[data-piece]")
+        for (const group of groups) {
+            const color = group.getAttribute("data-piece").charAt(0)
+            const piece = group.querySelector("use.piece")
+            if (piece) {
+                this.rotateElement(piece, this.angles[color], center)
+            }
+        }
+    }
+    /**
+     * The rotation is the transform appended after the ones the view sets, its
+     * index in the list is stored on the element. The item is addressed by
+     * position, not by a retained object reference: WebKit returns fresh
+     * wrapper objects from `getItem`, an identity check would report the
+     * transform as lost on every call and stale rotations would pile up.
+     */
+    rotateElement(element, angle, center) {
+        const list = element.transform.baseVal
+        let index = parseInt(element.getAttribute("data-rotation-index"), 10)
+        if (isNaN(index) || index >= list.numberOfItems) {
+            index = list.numberOfItems
+            list.appendItem(element.ownerSVGElement.createSVGTransform())
+            element.setAttribute("data-rotation-index", index)
+        }
+        list.getItem(index).setRotate(angle, center, center)
+    }
+}

package/src/extensions/piece-rotation/README.md ADDED Viewed

@@ -0,0 +1,39 @@
+# PieceRotation extension
+Rotates the piece glyphs in place, by any angle, optionally animated — either all pieces or only those of one color. The squares and the position stay untouched, only the glyphs turn around their own center.
+The main use case is over-the-board play on a tablet lying flat between two players: rotate the pieces by 180 degrees towards the player to move, so both players see their pieces upright.
+## Usage
+```js
+import {PieceRotation} from "cm-chessboard/src/extensions/piece-rotation/PieceRotation.js"
+const board = new Chessboard(context, {
+    position: FEN.start,
+    assetsUrl: "./assets/",
+    extensions: [{class: PieceRotation, props: {animationDuration: 300}}]
+})
+// rotate all pieces, animated, returns a Promise
+await board.setPiecesRotation(180)
+// rotate only the black pieces, not animated
+board.setPiecesRotation(180, {color: COLOR.black, animated: false})
+// the current target angle of a color (default COLOR.white)
+board.getPiecesRotation(COLOR.black)
+```
+## Props
+| Prop                | Default | Description                                            |
+|---------------------|---------|--------------------------------------------------------|
+| `angle`             | `0`     | Initial rotation angle in degrees, for all pieces      |
+| `animationDuration` | `300`   | Duration of an animated rotation in milliseconds       |
+## How it works
+The rotation is an additional `SVGTransform` appended to each piece's `use` element, after the translate and scale the view sets there. Appended last, it rotates in sprite coordinates around the tile center, so it composes with any piece position and survives the move animations, which only touch the translate of the surrounding group. A `MutationObserver` on the pieces group re-applies the angles to freshly drawn pieces, so the rotation survives redraws and position changes from any code path.
+The rotation is independent of move input. The dragged ghost piece following the pointer is intentionally not rotated.

package/src/view/VisualMoveInput.js CHANGED Viewed

@@ -24,7 +24,9 @@ export const MOVE_CANCELED_REASON = {
     movedOutOfBoard: "movedOutOfBoard",
     draggedBack: "draggedBack", // dragged to the start square
     clickedAnotherPiece: "clickedAnotherPiece", // of the same color
-    touchCanceled: "touchCanceled"
+    touchCanceled: "touchCanceled",
+    movedPieceChanged: "movedPieceChanged", // the held piece changed on the board, most likely got captured
+    canceled: "canceled" // cancelled programmatically via chessboard.cancelMoveInput()
 }
 const DRAG_THRESHOLD = 4
@@ -37,6 +39,7 @@ export class VisualMoveInput {
         this.moveInputState = null
         this.fromSquare = null
         this.toSquare = null
+        this.movedPiece = null
         this.setMoveInputState(MOVE_INPUT_STATE.waitForInputStart)
     }
@@ -432,6 +435,40 @@ export class VisualMoveInput {
         this.moveInputCanceledCallback(this.fromSquare, null, MOVE_CANCELED_REASON.secondaryClick)
     }
+    // Cancel a move input that is currently in progress. No-op when idle.
+    cancelMoveInput() {
+        if (this.moveInputState !== MOVE_INPUT_STATE.waitForInputStart) {
+            const moveStartSquare = this.fromSquare
+            this.view.redrawPieces()
+            this.setMoveInputState(MOVE_INPUT_STATE.reset)
+            this.moveInputCanceledCallback(moveStartSquare, null, MOVE_CANCELED_REASON.canceled)
+        }
+    }
+    // Called after the board position changed (setPosition/movePiece/setPiece).
+    // If the piece we are holding changed on its square — most likely captured
+    // by an external position update — cancel the in-progress move input.
+    positionChanged() {
+        // Only cancel while actually holding a piece. Never in moveDone/reset:
+        // completing a move itself goes through movePiece() and must not self-cancel.
+        const holdingStates = [
+            MOVE_INPUT_STATE.pieceClickedThreshold,
+            MOVE_INPUT_STATE.clickTo,
+            MOVE_INPUT_STATE.secondClickThreshold,
+            MOVE_INPUT_STATE.dragTo,
+            MOVE_INPUT_STATE.clickDragTo
+        ]
+        if (this.fromSquare && holdingStates.includes(this.moveInputState) &&
+            this.chessboard.getPiece(this.fromSquare) !== this.movedPiece) {
+            const moveStartSquare = this.fromSquare
+            // drop the stale held piece so the reset branch does not stamp it
+            // back onto the square, overwriting the piece just placed there
+            this.movedPiece = null
+            this.setMoveInputState(MOVE_INPUT_STATE.reset)
+            this.moveInputCanceledCallback(moveStartSquare, null, MOVE_CANCELED_REASON.movedPieceChanged)
+        }
+    }
     isDragging() {
         return this.moveInputState === MOVE_INPUT_STATE.dragTo || this.moveInputState === MOVE_INPUT_STATE.clickDragTo
     }

package/test/TestPieceRotation.js ADDED Viewed

@@ -0,0 +1,138 @@
+/**
+ * Author and copyright: Stefan Haack (https://shaack.com)
+ * Repository: https://github.com/shaack/cm-chessboard
+ * License: MIT, see file 'LICENSE'
+ */
+import {describe, it, assert} from "../node_modules/teevi/src/teevi.js"
+import {Chessboard, COLOR} from "../src/Chessboard.js"
+import {FEN} from "../src/model/Position.js"
+import {PieceRotation} from "../src/extensions/piece-rotation/PieceRotation.js"
+function makeBoard(props = {}) {
+    return new Chessboard(document.getElementById("TestPieceRotation"), {
+        position: FEN.start,
+        assetsUrl: "../assets/",
+        ...props
+    })
+}
+function rotationOf(useElement) {
+    // the appended rotation is the last transform in the list
+    const list = useElement.transform.baseVal
+    const item = list.getItem(list.numberOfItems - 1)
+    return item.type === SVGTransform.SVG_TRANSFORM_ROTATE ? item.angle : null
+}
+function piecesOf(chessboard, color) {
+    return chessboard.view.piecesGroup.querySelectorAll(`g[data-piece^="${color}"] use.piece`)
+}
+// The MutationObserver in the extension applies the angles to freshly drawn
+// pieces in a microtask, wait one tick before asserting.
+function nextTick() {
+    return new Promise((resolve) => setTimeout(resolve))
+}
+describe("TestPieceRotation", () => {
+    it("should rotate all pieces instantly and back", async () => {
+        const chessboard = makeBoard({extensions: [{class: PieceRotation}]})
+        assert.equal(chessboard.getPiecesRotation(), 0)
+        await chessboard.setPiecesRotation(180, {animated: false})
+        assert.equal(chessboard.getPiecesRotation(COLOR.white), 180)
+        assert.equal(chessboard.getPiecesRotation(COLOR.black), 180)
+        const pieces = chessboard.view.piecesGroup.querySelectorAll("use.piece")
+        assert.equal(pieces.length, 32)
+        for (const piece of pieces) {
+            assert.equal(rotationOf(piece), 180)
+        }
+        await chessboard.setPiecesRotation(0, {animated: false})
+        for (const piece of pieces) {
+            assert.equal(rotationOf(piece), 0)
+        }
+        chessboard.destroy()
+    })
+    it("should rotate only one color", async () => {
+        const chessboard = makeBoard({extensions: [{class: PieceRotation}]})
+        await chessboard.setPiecesRotation(180, {color: COLOR.black, animated: false})
+        assert.equal(chessboard.getPiecesRotation(COLOR.black), 180)
+        assert.equal(chessboard.getPiecesRotation(COLOR.white), 0)
+        for (const piece of piecesOf(chessboard, "b")) {
+            assert.equal(rotationOf(piece), 180)
+        }
+        for (const piece of piecesOf(chessboard, "w")) {
+            assert.equal(rotationOf(piece), 0)
+        }
+        chessboard.destroy()
+    })
+    it("should animate the rotation to the target angle", async () => {
+        const chessboard = makeBoard({
+            extensions: [{class: PieceRotation, props: {animationDuration: 50}}]
+        })
+        await chessboard.setPiecesRotation(90)
+        const pieces = chessboard.view.piecesGroup.querySelectorAll("use.piece")
+        assert.equal(pieces.length, 32)
+        for (const piece of pieces) {
+            assert.equal(rotationOf(piece), 90)
+        }
+        chessboard.destroy()
+    })
+    it("should keep the rotation on pieces after a position change", async () => {
+        const chessboard = makeBoard({extensions: [{class: PieceRotation}]})
+        await chessboard.setPiecesRotation(180, {animated: false})
+        await chessboard.movePiece("e2", "e4", false)
+        await nextTick()
+        const moved = chessboard.view.piecesGroup.querySelector('g[data-square="e4"] use.piece')
+        assert.true(moved !== null)
+        assert.equal(rotationOf(moved), 180)
+        // all the other pieces keep it too
+        const pieces = chessboard.view.piecesGroup.querySelectorAll("use.piece")
+        for (const piece of pieces) {
+            assert.equal(rotationOf(piece), 180)
+        }
+        chessboard.destroy()
+    })
+    it("should keep the rotation after an animated move", async () => {
+        const chessboard = makeBoard({
+            style: {animationDuration: 50},
+            extensions: [{class: PieceRotation}]
+        })
+        await chessboard.setPiecesRotation(180, {animated: false})
+        await chessboard.movePiece("b1", "c3", true)
+        await nextTick()
+        const moved = chessboard.view.piecesGroup.querySelector('g[data-square="c3"] use.piece')
+        assert.true(moved !== null)
+        assert.equal(rotationOf(moved), 180)
+        chessboard.destroy()
+    })
+    it("should apply an initial angle from the props", async () => {
+        const chessboard = makeBoard({
+            extensions: [{class: PieceRotation, props: {angle: 180}}]
+        })
+        await nextTick()
+        for (const piece of chessboard.view.piecesGroup.querySelectorAll("use.piece")) {
+            assert.equal(rotationOf(piece), 180)
+        }
+        chessboard.destroy()
+    })
+    it("should supersede a running animation", async () => {
+        const chessboard = makeBoard({
+            extensions: [{class: PieceRotation, props: {animationDuration: 1000}}]
+        })
+        chessboard.setPiecesRotation(180) // not awaited, will be superseded
+        await chessboard.setPiecesRotation(45, {animated: false})
+        assert.equal(chessboard.getPiecesRotation(), 45)
+        const pieces = chessboard.view.piecesGroup.querySelectorAll("use.piece")
+        for (const piece of pieces) {
+            assert.equal(rotationOf(piece), 45)
+        }
+        chessboard.destroy()
+    })
+})

package/test/TestVisualMoveInput.js CHANGED Viewed

@@ -231,4 +231,131 @@ describe("TestVisualMoveInput", () => {
         board.destroy()
     })
+    // Regression for https://github.com/shaack/cm-chessboard/pull/165
+    it("should cancel and keep the new position when the held piece is captured via setPosition", async () => {
+        const board = newBoard()
+        let canceled = null
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceled = {square: e.squareFrom, reason: e.reason}
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+        // the opponent captures the held e2 pawn (e2 now holds a black knight)
+        const capturedFen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPnPPP/RNBQKBNR"
+        await board.setPosition(capturedFen)
+        assert.equal(canceled && canceled.reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        assert.equal(canceled && canceled.square, "e2") // the real start square, not null
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        // the position must not be corrupted back to the white pawn
+        assert.equal("" + board.getPosition(), capturedFen)
+        await tick()
+        board.destroy()
+    })
+    it("should not cancel a normal move completion", async () => {
+        const board = newBoard()
+        let canceledReason
+        let finished = 0
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledReason = e.reason
+            if (e.type === INPUT_EVENT_TYPE.moveInputFinished) finished++
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        vmi.onPointerDown(mouseDown("e4")) // completes via moveDone -> movePiece()
+        await tick()
+        assert.equal(board.getPiece("e4"), "wp")
+        assert.equal(canceledReason, undefined) // the guard must prevent a spurious cancel
+        assert.equal(finished, 1)
+        board.destroy()
+    })
+    it("should cancel when the held piece is captured via movePiece or setPiece", async () => {
+        // via setPiece
+        let board = newBoard()
+        let reason
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) reason = e.reason
+            return true
+        }, COLOR.white)
+        let vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        await board.setPiece("e2", "bn")
+        assert.equal(reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        await tick()
+        board.destroy()
+        // via movePiece (a black pawn captures onto e2)
+        board = newBoard()
+        reason = undefined
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) reason = e.reason
+            return true
+        }, COLOR.white)
+        vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        await board.movePiece("d7", "e2")
+        assert.equal(reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        await tick()
+        board.destroy()
+    })
+    it("should cancel an in-progress click selection via cancelMoveInput()", async () => {
+        const board = newBoard()
+        let canceled = null
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceled = {square: e.squareFrom, reason: e.reason}
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+        board.cancelMoveInput()
+        assert.equal(canceled && canceled.reason, MOVE_CANCELED_REASON.canceled)
+        assert.equal(canceled && canceled.square, "e2")
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        await tick()
+        board.destroy()
+    })
+    it("should cancel a drag in progress via cancelMoveInput() without moving the piece", async () => {
+        const board = newBoard()
+        board.enableMoveInput(() => true, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2", 100, 100))
+        vmi.onPointerMove(mouseMove("e4", 100, 140)) // -> dragTo
+        assert.equal(vmi.moveInputState, STATE_DRAG_TO)
+        board.cancelMoveInput()
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        assert.equal(board.getPiece("e2"), "wp")
+        assert.equal(board.getPiece("e4"), null)
+        await tick()
+        board.destroy()
+    })
+    it("should be a no-op when cancelMoveInput() is called with no move in progress", () => {
+        const board = newBoard()
+        let canceledCount = 0
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledCount++
+            return true
+        }, COLOR.white)
+        board.cancelMoveInput()
+        assert.equal(canceledCount, 0)
+        assert.equal(board.view.visualMoveInput.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        board.destroy()
+    })
 })

package/test/index.html CHANGED Viewed

@@ -21,6 +21,7 @@
 <div class="board" id="TestPosition"></div>
 <div class="board" id="TestMarkers"></div>
 <div class="board" id="TestArrows"></div>
+<div class="board" id="TestPieceRotation"></div>
 <script type="module">
     import {teevi} from "../node_modules/teevi/src/teevi.js"
     import "./TestChessboard.js"
@@ -29,6 +30,7 @@
     import "./TestArrows.js"
     import "./TestPosition.js"
     import "./TestVisualMoveInput.js"
+    import "./TestPieceRotation.js"
     teevi.run()
 </script>
 </body>