@prosopo/procaptcha-puzzle 2.12.2 → 2.13.0

package/src/components/PuzzleCanvas.tsx

@@ -12,10 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { ChallengeSurface } from "@prosopo/procaptcha-common";
+import { useTranslation } from "@prosopo/locale";
+import { ChallengeSurface, isEventTrusted } from "@prosopo/procaptcha-common";
 import type { PlacementType, PuzzleEvent } from "@prosopo/types";
 import type { Theme } from "@prosopo/widget-skeleton";
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	type CSSProperties,
+	useCallback,
+	useEffect,
+	useId,
+	useRef,
+	useState,
+} from "react";
 
 interface PuzzleCanvasProps {
 	originX: number;
@@ -42,12 +50,43 @@ interface PuzzleCanvasProps {
 const CONTAINER_WIDTH = 300;
 const CONTAINER_HEIGHT = 200;
 
-const SHAKE_KEYFRAMES = `
+const PIECE_CSS_CLASS = "prosopo-puzzle-piece";
+
+// An arrow press moves a tenth of the board's width. The provider accepts a
+// solution within 15px of the target, so a 10px lattice always contains a
+// winning cell (worst case is half a diagonal, ~7.1px) — a keyboard user can
+// land the piece without ever needing the finer step.
+const STEP_PX = 10;
+const FINE_STEP_PX = 2;
+
+// Arrow keys repeat far faster than a screen reader speaks. Coalescing to the
+// last position after a pause keeps the running commentary from queueing up
+// behind the user and reporting somewhere they left several seconds ago.
+const ANNOUNCE_DEBOUNCE_MS = 400;
+
+const VISUALLY_HIDDEN: CSSProperties = {
+	position: "absolute",
+	width: "1px",
+	height: "1px",
+	padding: 0,
+	margin: "-1px",
+	overflow: "hidden",
+	clip: "rect(0, 0, 0, 0)",
+	clipPath: "inset(50%)",
+	whiteSpace: "nowrap",
+	border: 0,
+};
+
+const stylesheet = (focusRingColor: string): string => `
 @keyframes prosopo-puzzle-shake {
 	0%, 100% { transform: translateX(0); }
 	10%, 30%, 50%, 70%, 90% { transform: translateX(-4px); }
 	20%, 40%, 60%, 80% { transform: translateX(4px); }
 }
+.${PIECE_CSS_CLASS}:focus-visible {
+	outline: 3px solid ${focusRingColor};
+	outline-offset: 2px;
+}
 `;
 
 export const PuzzleCanvas = ({
@@ -77,11 +116,21 @@ export const PuzzleCanvas = ({
 	const offsetRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
 	const [visible, setVisible] = useState(false);
 	const [shaking, setShaking] = useState(false);
+	const { t } = useTranslation();
+	const baseId = useId();
+	const instructionId = `${baseId}-instruction`;
+	const keyboardHintId = `${baseId}-keyboard-hint`;
+	// Set to true by the first arrow press of a keyboard run, so the run starts
+	// from a clean trail exactly as a fresh mouse grab does.
+	const keyboardDragging = useRef<boolean>(false);
+	const [announcement, setAnnouncement] = useState<string>("");
+	const announceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
 	// Reset piece position when challenge data changes (new puzzle on retry)
 	useEffect(() => {
 		setPosX(originX);
 		setPosY(originY);
+		keyboardDragging.current = false;
 	}, [originX, originY]);
 
 	// Trigger entrance animation after mount
@@ -107,6 +156,38 @@ export const PuzzleCanvas = ({
 		[],
 	);
 
+	const announce = useCallback((message: string, delayMs = 0): void => {
+		if (announceTimer.current) {
+			clearTimeout(announceTimer.current);
+			announceTimer.current = null;
+		}
+		if (delayMs === 0) {
+			setAnnouncement(message);
+			return;
+		}
+		announceTimer.current = setTimeout(() => setAnnouncement(message), delayMs);
+	}, []);
+
+	useEffect(
+		() => () => {
+			if (announceTimer.current) clearTimeout(announceTimer.current);
+		},
+		[],
+	);
+
+	// Pixel coordinates mean nothing to someone who cannot see the board, and
+	// the widget is never told where the target is, so proportions are the only
+	// bearing it can honestly offer.
+	const describePosition = useCallback(
+		(x: number, y: number): string =>
+			t("WIDGET.PUZZLE.POSITION", {
+				defaultValue: "{{x}} percent across, {{y}} percent down",
+				x: Math.round((x / CONTAINER_WIDTH) * 100),
+				y: Math.round((y / CONTAINER_HEIGHT) * 100),
+			}),
+		[t],
+	);
+
 	const getContainerOffset = useCallback((): { x: number; y: number } => {
 		if (containerRef.current) {
 			const rect = containerRef.current.getBoundingClientRect();
@@ -141,6 +222,13 @@ export const PuzzleCanvas = ({
 		[clamp, getContainerOffset],
 	);
 
+	const complete = useCallback(
+		(finalX: number, finalY: number): void => {
+			onComplete(finalX, finalY, [...puzzleEvents.current]);
+		},
+		[onComplete],
+	);
+
 	const handleEndEvent = useCallback(() => {
 		if (!isDragging.current) {
 			return;
@@ -149,13 +237,12 @@ export const PuzzleCanvas = ({
 		isDragging.current = false;
 		setDragging(false);
 
-		const currentEvents = [...puzzleEvents.current];
-		const lastEvent = currentEvents[currentEvents.length - 1];
-		const finalX = lastEvent ? lastEvent.x : originX;
-		const finalY = lastEvent ? lastEvent.y : originY;
-
-		onComplete(finalX, finalY, currentEvents);
-	}, [onComplete, originX, originY]);
+		const lastEvent = puzzleEvents.current[puzzleEvents.current.length - 1];
+		complete(
+			lastEvent ? lastEvent.x : originX,
+			lastEvent ? lastEvent.y : originY,
+		);
+	}, [complete, originX, originY]);
 
 	const handleMouseMove = useCallback(
 		(event: MouseEvent) => {
@@ -200,6 +287,7 @@ export const PuzzleCanvas = ({
 		(event: React.MouseEvent<HTMLDivElement>) => {
 			if (submitting) return;
 			isDragging.current = true;
+			keyboardDragging.current = false;
 			setDragging(true);
 			puzzleEvents.current = [];
 			const containerOffset = getContainerOffset();
@@ -217,6 +305,7 @@ export const PuzzleCanvas = ({
 			const touch = event.touches[0];
 			if (touch) {
 				isDragging.current = true;
+				keyboardDragging.current = false;
 				setDragging(true);
 				puzzleEvents.current = [];
 				const containerOffset = getContainerOffset();
@@ -229,9 +318,87 @@ export const PuzzleCanvas = ({
 		[getContainerOffset, posX, posY, submitting],
 	);
 
+	const moveByKeyboard = useCallback(
+		(deltaX: number, deltaY: number): void => {
+			if (!keyboardDragging.current) {
+				keyboardDragging.current = true;
+				puzzleEvents.current = [];
+			}
+
+			const nextX = clamp(posX + deltaX, 0, CONTAINER_WIDTH);
+			const nextY = clamp(posY + deltaY, 0, CONTAINER_HEIGHT);
+
+			setPosX(nextX);
+			setPosY(nextY);
+			puzzleEvents.current.push({ x: nextX, y: nextY, t: Date.now() });
+			announce(describePosition(nextX, nextY), ANNOUNCE_DEBOUNCE_MS);
+		},
+		[announce, clamp, describePosition, posX, posY],
+	);
+
+	const handlePieceKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLDivElement>): void => {
+			if (submitting) return;
+			if (!isEventTrusted(event)) return;
+
+			const step = event.shiftKey ? FINE_STEP_PX : STEP_PX;
+			const moves: Record<string, [number, number] | undefined> = {
+				ArrowLeft: [-step, 0],
+				ArrowRight: [step, 0],
+				ArrowUp: [0, -step],
+				ArrowDown: [0, step],
+				Home: [originX - posX, originY - posY],
+			};
+
+			const move = moves[event.key];
+			if (move) {
+				event.preventDefault();
+				moveByKeyboard(move[0], move[1]);
+				return;
+			}
+
+			if (event.key === "Enter" || event.key === " ") {
+				event.preventDefault();
+				// Ends the run, so the next arrow press opens a clean trail just
+				// as the next mouse grab would.
+				keyboardDragging.current = false;
+				complete(posX, posY);
+			}
+		},
+		[complete, moveByKeyboard, originX, originY, posX, posY, submitting],
+	);
+
+	const handlePieceFocus = useCallback((): void => {
+		announce(describePosition(posX, posY));
+	}, [announce, describePosition, posX, posY]);
+
 	const instructionText = showRetry
-		? "Not quite \u2014 try again"
-		: "Drag the piece to the target";
+		? t("WIDGET.PUZZLE.RETRY", { defaultValue: "Not quite \u2014 try again" })
+		: t("WIDGET.PUZZLE.DRAG", {
+				defaultValue: "Drag the piece to the target",
+			});
+
+	const keyboardHintText = t("WIDGET.PUZZLE.KEYBOARD_HINT", {
+		defaultValue:
+			"Use the arrow keys to move the piece, holding shift for smaller steps. Press Enter to submit it, Home to put it back at the start, or Escape to cancel.",
+	});
+
+	useEffect(() => {
+		if (!submitting) return;
+		announce(
+			t("WIDGET.PUZZLE.CHECKING", { defaultValue: "Checking your answer" }),
+		);
+	}, [submitting, announce, t]);
+
+	useEffect(() => {
+		if (!showRetry) return;
+		announce(
+			t("WIDGET.PUZZLE.RETRY_ANNOUNCEMENT", {
+				defaultValue:
+					"Not quite. A new puzzle has loaded and the piece is back at the start.",
+			}),
+		);
+	}, [showRetry, announce, t]);
 
 	const headerBorderColor = showRetry
 		? theme.palette.error.main
@@ -273,9 +440,22 @@ export const PuzzleCanvas = ({
 			anchor={anchor}
 			onDismiss={onDismiss}
 			scrim={visible ? "dim" : "none"}
+			dialogLabel={t("WIDGET.PUZZLE.DIALOG_LABEL", {
+				defaultValue: "Puzzle challenge",
+			})}
 		>
-			{/* Inject shake keyframes */}
-			<style>{SHAKE_KEYFRAMES}</style>
+			<style>{stylesheet(theme.palette.primary.main)}</style>
+
+			{/* Progress the piece cannot show a screen reader: where it has got
+			    to, that a solution is being checked, and that a failed go has
+			    been replaced by a fresh puzzle. */}
+			<output aria-live="polite" aria-atomic="true" style={VISUALLY_HIDDEN}>
+				{announcement}
+			</output>
+
+			<div id={keyboardHintId} style={VISUALLY_HIDDEN}>
+				{keyboardHintText}
+			</div>
 
 			<div
 				style={{
@@ -291,6 +471,7 @@ export const PuzzleCanvas = ({
 			>
 				{/* Instruction text */}
 				<div
+					id={instructionId}
 					style={{
 						backgroundColor: theme.palette.surface,
 						borderRadius: "20px 20px 0 0",
@@ -387,20 +568,41 @@ export const PuzzleCanvas = ({
 							);
 						})}
 					</div>
-					{/* Puzzle piece */}
+					{/* Puzzle piece.
+
+					    `application` rather than `button`: in the browse mode
+					    NVDA and JAWS default to, arrow keys move the reading
+					    cursor through the page and never reach a button's key
+					    handler. `application` is the role that hands them
+					    straight to this element, which is what makes the drag
+					    reachable without a pointer at all.
+
+					    The role and class are a stable production selector,
+					    which the data-cy below is deliberately not. A scripted
+					    solver could already find this element — it is the only
+					    draggable thing on the surface — whereas without them a
+					    keyboard or screen-reader user cannot find it at all. */}
 					<div
 						// Test-only selector: gated on NODE_ENV !== "production"
 						// so esbuild constant-folds it out of production bundles.
-						// The whole point of the puzzle drag is that a bot
-						// shouldn't be able to `querySelector` its way to the
-						// interactive element; shipping a stable data-cy would
-						// hand that to any scripted solver for free. Cypress
-						// builds the bundle with NODE_ENV=development
+						// Cypress builds the bundle with NODE_ENV=development
 						// (.github/workflows/cypress.yml:110) so the selector
 						// is present under test.
 						{...(process.env.NODE_ENV !== "production" && {
 							"data-cy": "prosopo-puzzle-piece",
 						})}
+						className={PIECE_CSS_CLASS}
+						role="application"
+						aria-roledescription={t("WIDGET.PUZZLE.PIECE_ROLE", {
+							defaultValue: "draggable puzzle piece",
+						})}
+						aria-label={t("WIDGET.PUZZLE.PIECE_LABEL", {
+							defaultValue: "Puzzle piece",
+						})}
+						aria-describedby={`${instructionId} ${keyboardHintId}`}
+						tabIndex={submitting ? -1 : 0}
+						onFocus={handlePieceFocus}
+						onKeyDown={handlePieceKeyDown}
 						onMouseDown={handlePieceMouseDown}
 						onTouchStart={handlePieceTouchStart}
 						style={{

package/src/tests/puzzleCanvas.unit.test.ts

@@ -34,6 +34,26 @@ import { PuzzleCanvas } from "../components/PuzzleCanvas.js";
  * against a real render rather than calling the handlers directly.
  */
 
+/**
+ * The real locale package reaches for an http backend the moment a component
+ * asks it for a string, which jsdom refuses. The English defaults the canvas
+ * ships stand in instead, interpolated the way i18next would, so the
+ * assertions below read as the copy a user is actually given.
+ */
+vi.mock("@prosopo/locale", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("@prosopo/locale")>();
+	const t = (
+		key: string,
+		options?: { defaultValue?: string } & Record<string, unknown>,
+	): string =>
+		(options?.defaultValue ?? key).replace(
+			/{{(\w+)}}/g,
+			(placeholder: string, name: string) =>
+				options && name in options ? String(options[name]) : placeholder,
+		);
+	return { ...actual, useTranslation: () => ({ t, ready: true }) };
+});
+
 const CONTAINER_WIDTH = 300;
 const CONTAINER_HEIGHT = 200;
 const PIECE_SIZE = 44;
@@ -151,7 +171,53 @@ const touchEnd = (): void => {
 	});
 };
 
+const keyDown = (key: string, options: { shiftKey?: boolean } = {}): void => {
+	act(() => {
+		piece().dispatchEvent(
+			new KeyboardEvent("keydown", {
+				key,
+				bubbles: true,
+				cancelable: true,
+				shiftKey: options.shiftKey ?? false,
+			}),
+		);
+	});
+};
+
+/**
+ * `isTrusted` is unforgeable, so jsdom can only ever produce the synthetic
+ * events the canvas refuses. Opening the allowance is how the firefox cypress
+ * leg drives the widget too; the gate itself is covered by the one test that
+ * shuts it again.
+ */
+const allowSyntheticEvents = (allowed: boolean): void => {
+	vi.stubGlobal("__PROSOPO_ALLOW_UNTRUSTED_EVENTS__", allowed);
+};
+
+const required = (element: HTMLElement | null, what: string): HTMLElement => {
+	if (!element) throw new Error(`expected ${what} to be rendered`);
+	return element;
+};
+
+const dialog = (): HTMLElement =>
+	required(
+		overlay().querySelector<HTMLElement>('[role="dialog"]'),
+		"the dialog",
+	);
+
+/** An `output` element carries the implicit `status` role a live region needs. */
+const liveRegion = (): HTMLElement =>
+	required(overlay().querySelector<HTMLElement>("output"), "the live region");
+
+/** The text a screen reader reads out when the piece takes focus. */
+const pieceDescription = (): string =>
+	(piece().getAttribute("aria-describedby") ?? "")
+		.split(" ")
+		.map((id) => document.getElementById(id)?.textContent ?? "")
+		.join(" ");
+
 beforeEach(() => {
+	allowSyntheticEvents(true);
 	onComplete =
 		vi.fn<
 			(finalX: number, finalY: number, puzzleEvents: PuzzleEvent[]) => void
@@ -169,6 +235,7 @@ afterEach(() => {
 	});
 	container.remove();
 	vi.useRealTimers();
+	vi.unstubAllGlobals();
 	vi.restoreAllMocks();
 });
 
@@ -413,6 +480,199 @@ describe("dragging with a finger", () => {
 	});
 });
 
+describe("driving it from the keyboard", () => {
+	test("the piece takes focus as soon as the puzzle opens", () => {
+		render(props());
+		expect(document.activeElement).toBe(piece());
+	});
+
+	test("an arrow key walks the piece a step across the board", () => {
+		render(props());
+		keyDown("ArrowRight");
+		expect(piecePosition()).toEqual({ x: 30, y: 100 });
+	});
+
+	test("holding shift walks it a finer step", () => {
+		render(props());
+		keyDown("ArrowRight", { shiftKey: true });
+		expect(piecePosition()).toEqual({ x: 22, y: 100 });
+	});
+
+	test("all four arrows move the piece the way they point", () => {
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("ArrowDown");
+		keyDown("ArrowLeft");
+		keyDown("ArrowUp");
+		expect(piecePosition()).toEqual({ x: 20, y: 100 });
+	});
+
+	test("the board's edge stops the piece just as a drag does", () => {
+		render(props());
+		for (let press = 0; press < 5; press++) keyDown("ArrowLeft");
+		expect(piecePosition()).toEqual({ x: 0, y: 100 });
+	});
+
+	test("home puts the piece back where it started", () => {
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("ArrowDown");
+		keyDown("Home");
+		expect(piecePosition()).toEqual({ x: 20, y: 100 });
+	});
+
+	test("enter hands over where the piece is, with the trail", () => {
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("ArrowRight");
+		keyDown("Enter");
+		expect(onComplete).toHaveBeenCalledTimes(1);
+		const [finalX, finalY, events] = onComplete.mock.calls[0] ?? [];
+		expect(finalX).toBe(40);
+		expect(finalY).toBe(100);
+		expect(events?.map((event) => [event.x, event.y])).toEqual([
+			[30, 100],
+			[40, 100],
+		]);
+	});
+
+	test("space submits too", () => {
+		render(props());
+		keyDown("ArrowRight");
+		keyDown(" ");
+		expect(onComplete).toHaveBeenCalledWith(30, 100, [
+			expect.objectContaining({ x: 30, y: 100 }),
+		]);
+	});
+
+	test("a second keyboard go starts from a clean trail", () => {
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("Enter");
+		keyDown("ArrowDown");
+		keyDown("Enter");
+		const events = onComplete.mock.calls[1]?.[2];
+		expect(events?.map((event) => [event.x, event.y])).toEqual([[30, 110]]);
+	});
+
+	test("a key press no user made is ignored", () => {
+		allowSyntheticEvents(false);
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("Enter");
+		expect(piecePosition()).toEqual({ x: 20, y: 100 });
+		expect(onComplete).not.toHaveBeenCalled();
+	});
+
+	test("keys that mean nothing here are left to the page", () => {
+		render(props());
+		keyDown("a");
+		expect(piecePosition()).toEqual({ x: 20, y: 100 });
+		expect(onComplete).not.toHaveBeenCalled();
+	});
+
+	test("the piece cannot be moved or submitted while a solution is in flight", () => {
+		render(props({ submitting: true }));
+		keyDown("ArrowRight");
+		keyDown("Enter");
+		expect(piecePosition()).toEqual({ x: 20, y: 100 });
+		expect(onComplete).not.toHaveBeenCalled();
+	});
+
+	test("nor can it be tabbed to while a solution is in flight", () => {
+		render(props({ submitting: true }));
+		expect(piece().tabIndex).toBe(-1);
+	});
+
+	test("tab cannot leave the dialog for the page behind it", () => {
+		render(props());
+		act(() => {
+			document.dispatchEvent(
+				new KeyboardEvent("keydown", { key: "Tab", bubbles: true }),
+			);
+		});
+		expect(document.activeElement).toBe(piece());
+	});
+
+	test("closing hands focus back to whatever opened the puzzle", () => {
+		const opener = document.createElement("button");
+		document.body.appendChild(opener);
+		opener.focus();
+
+		render(props());
+		expect(document.activeElement).toBe(piece());
+
+		act(() => {
+			root.unmount();
+		});
+		expect(document.activeElement).toBe(opener);
+
+		opener.remove();
+		act(() => {
+			root = createRoot(container);
+		});
+	});
+});
+
+describe("what it says to a screen reader", () => {
+	test("the panel announces itself as a named dialog", () => {
+		render(props());
+		expect(dialog().getAttribute("aria-label")).toBe("Puzzle challenge");
+		expect(dialog().getAttribute("aria-modal")).toBe("true");
+	});
+
+	test("the piece carries a name and says it can be dragged", () => {
+		render(props());
+		expect(piece().getAttribute("aria-label")).toBe("Puzzle piece");
+		expect(piece().getAttribute("aria-roledescription")).toBe(
+			"draggable puzzle piece",
+		);
+	});
+
+	test("the piece is described by the instruction and the key help", () => {
+		render(props());
+		expect(pieceDescription()).toContain("Drag the piece to the target");
+		expect(pieceDescription()).toContain("arrow keys");
+		expect(pieceDescription()).toContain("Escape");
+	});
+
+	test("taking focus reports where the piece is, in proportions", () => {
+		render(props());
+		expect(liveRegion().textContent).toBe("7 percent across, 50 percent down");
+	});
+
+	test("a move is reported once the keys stop, not on every press", () => {
+		vi.useFakeTimers();
+		render(props());
+		keyDown("ArrowRight");
+		keyDown("ArrowRight");
+		expect(liveRegion().textContent).toBe("7 percent across, 50 percent down");
+		act(() => {
+			vi.advanceTimersByTime(500);
+		});
+		expect(liveRegion().textContent).toBe("13 percent across, 50 percent down");
+	});
+
+	test("a solution in flight is announced", () => {
+		render(props({ submitting: true }));
+		expect(liveRegion().textContent).toBe("Checking your answer");
+	});
+
+	test("a retry says the puzzle has been replaced", () => {
+		render(props({ showRetry: true }));
+		expect(liveRegion().textContent).toContain("A new puzzle has loaded");
+	});
+
+	test("the background tiles are left out of the reading order", () => {
+		render(props());
+		const images = Array.from(overlay().querySelectorAll("img"));
+		expect(images.length).toBeGreaterThan(0);
+		expect(images.every((image) => image.getAttribute("alt") === "")).toBe(
+			true,
+		);
+	});
+});
+
 describe("after it goes away", () => {
 	test("its document listeners go with it", () => {
 		render(props());