@prosopo/procaptcha-common 2.12.5 → 2.13.0

package/src/reactComponents/ChallengeSurface.tsx

@@ -0,0 +1,285 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { PlacementEnum, type PlacementType } from "@prosopo/types";
+import React, {
+	type CSSProperties,
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+import { createPortal } from "react-dom";
+
+/**
+ * The layer every challenge is presented on. Portals to `document.body` so a
+ * host page's `overflow: hidden` or transformed ancestor cannot clip it.
+ * `popup` centres the content over the page; `float` anchors it to the widget.
+ */
+
+/** Scrim behind the content. Image has never dimmed the page; puzzle always has. */
+export type SurfaceScrim = "none" | "dim";
+
+interface ChallengeSurfaceProps {
+	show: boolean;
+	children: ReactNode;
+	placement?: PlacementType;
+	/** Element a floating challenge is positioned against. Without one, float falls back to popup. */
+	anchor?: HTMLElement | null;
+	scrim?: SurfaceScrim;
+	/** Called on Escape, and on an outside click when floating. */
+	onDismiss?: () => void;
+	/** Lifts the popup content on iOS, where Safari's bottom bar overlaps a centred dialog. */
+	popupIosLift?: boolean;
+	className?: string;
+}
+
+const SURFACE_Z_INDEX = 2147483646;
+const CONTENT_Z_INDEX = 2147483647;
+
+// `@supports` cannot be expressed inline, so the iOS lift is a stylesheet rule.
+const IOS_LIFT_STYLE_ID = "prosopo-challenge-surface-ios-lift";
+
+const IOS_LIFT_CSS = `
+.prosopo-challenge-content--ios-lift {
+	transform: translate(-50%, -50%);
+}
+@supports (-webkit-touch-callout: none) {
+	.prosopo-challenge-content--ios-lift {
+		transform: translate(-50%, -100%);
+	}
+}
+`;
+
+const ensureIosLiftStyles = (): void => {
+	if (typeof document === "undefined") return;
+	if (document.getElementById(IOS_LIFT_STYLE_ID)) return;
+
+	const style = document.createElement("style");
+	style.id = IOS_LIFT_STYLE_ID;
+	style.textContent = IOS_LIFT_CSS;
+	document.head.appendChild(style);
+};
+
+const FLOAT_GAP_PX = 8;
+
+const useIsomorphicLayoutEffect =
+	typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+interface FloatPosition {
+	top: number;
+	left: number;
+}
+
+/**
+ * Places the panel directly above the anchor, in document coordinates.
+ *
+ * Document coordinates rather than viewport ones, because the panel is
+ * `position: absolute`: the page carries it while scrolling instead of the
+ * panel being recomputed against a moving viewport, which is what made it
+ * drift. Always above, never flipped, so the challenge does not jump to the
+ * other side of the widget as the page moves.
+ */
+const computeFloatPosition = (
+	anchorRect: DOMRect,
+	panelHeight: number,
+	scrollX: number,
+	scrollY: number,
+): FloatPosition => ({
+	// Clamped at the top of the document so a widget near the top of the page
+	// cannot push the panel out of reach.
+	top: Math.max(0, anchorRect.top + scrollY - panelHeight - FLOAT_GAP_PX),
+	left: anchorRect.left + scrollX,
+});
+
+const ChallengeSurface = React.memo((props: ChallengeSurfaceProps) => {
+	const {
+		show,
+		children,
+		placement = PlacementEnum.popup,
+		anchor,
+		scrim = "none",
+		onDismiss,
+		popupIosLift = false,
+		className,
+	} = props;
+
+	const contentRef = useRef<HTMLDivElement>(null);
+	const [floatPosition, setFloatPosition] = useState<FloatPosition | null>(
+		null,
+	);
+
+	const isFloating = placement === PlacementEnum.float && !!anchor;
+
+	const reposition = useCallback(() => {
+		if (!isFloating || !anchor || !contentRef.current) return;
+		const panel = contentRef.current.getBoundingClientRect();
+		const next = computeFloatPosition(
+			anchor.getBoundingClientRect(),
+			panel.height,
+			window.scrollX,
+			window.scrollY,
+		);
+		// Reflow and panel-size changes fire more often than the panel actually
+		// moves; keeping the previous object when nothing changed avoids a
+		// needless re-render.
+		setFloatPosition((current) =>
+			current && current.top === next.top && current.left === next.left
+				? current
+				: next,
+		);
+	}, [isFloating, anchor]);
+
+	// Layout effect so the first paint already has the panel in place.
+	useIsomorphicLayoutEffect(() => {
+		if (!show || !isFloating) {
+			setFloatPosition(null);
+			return;
+		}
+		reposition();
+	}, [show, isFloating, reposition]);
+
+	useEffect(() => {
+		if (!show || !isFloating) return;
+
+		// No scroll listener: the coordinates are document-relative, so the page
+		// scrolls the panel along with the widget on its own. Resize still
+		// matters because it can reflow the anchor to a new place in the page.
+		window.addEventListener("resize", reposition);
+
+		const observer =
+			typeof ResizeObserver === "function"
+				? new ResizeObserver(reposition)
+				: null;
+		if (observer && contentRef.current) observer.observe(contentRef.current);
+		if (observer && anchor) observer.observe(anchor);
+
+		return () => {
+			window.removeEventListener("resize", reposition);
+			observer?.disconnect();
+		};
+	}, [show, isFloating, anchor, reposition]);
+
+	useEffect(() => {
+		if (!show || !onDismiss) return;
+
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") onDismiss();
+		};
+		document.addEventListener("keydown", onKeyDown);
+		return () => document.removeEventListener("keydown", onKeyDown);
+	}, [show, onDismiss]);
+
+	useEffect(() => {
+		if (!show || !isFloating || !onDismiss) return;
+
+		const onPointerDown = (event: PointerEvent) => {
+			const target = event.target;
+			if (!(target instanceof Node)) return;
+			if (contentRef.current?.contains(target)) return;
+			// The anchor's own click is what opens the panel.
+			if (anchor?.contains(target)) return;
+			onDismiss();
+		};
+		document.addEventListener("pointerdown", onPointerDown);
+		return () => document.removeEventListener("pointerdown", onPointerDown);
+	}, [show, isFloating, anchor, onDismiss]);
+
+	useEffect(() => {
+		if (popupIosLift && !isFloating) ensureIosLiftStyles();
+	}, [popupIosLift, isFloating]);
+
+	if (typeof document === "undefined") return null;
+
+	const layerStyle: CSSProperties = isFloating
+		? {
+				// A zero-sized box at the document origin: it must not cover the
+				// page, and only its content takes pointer events. Absolute with
+				// no positioned ancestor resolves against the initial containing
+				// block, which is what makes the child's coordinates document
+				// coordinates.
+				position: "absolute",
+				top: 0,
+				left: 0,
+				width: 0,
+				height: 0,
+				zIndex: SURFACE_Z_INDEX,
+				display: show ? "block" : "none",
+				pointerEvents: "none",
+			}
+		: {
+				position: "fixed",
+				inset: 0,
+				zIndex: SURFACE_Z_INDEX,
+				display: show ? "flex" : "none",
+				alignItems: "center",
+				justifyContent: "center",
+				minHeight: "100vh",
+				backgroundColor:
+					scrim === "dim" && show ? "rgba(0, 0, 0, 0.4)" : "transparent",
+				transition: "background-color 0.3s ease",
+			};
+
+	const contentStyle: CSSProperties = isFloating
+		? {
+				position: "absolute",
+				zIndex: CONTENT_Z_INDEX,
+				pointerEvents: "auto",
+				top: `${floatPosition?.top ?? 0}px`,
+				left: `${floatPosition?.left ?? 0}px`,
+				// Hidden until the first measurement so it does not flash at 0,0.
+				visibility: floatPosition ? "visible" : "hidden",
+			}
+		: {
+				position: "absolute",
+				top: "50%",
+				left: "50%",
+				// When lifting, the stylesheet rule owns the transform.
+				transform: popupIosLift ? undefined : "translate(-50%, -50%)",
+				zIndex: CONTENT_Z_INDEX,
+				boxSizing: "border-box",
+			};
+
+	return createPortal(
+		<div
+			className={[
+				"prosopo-challenge-surface",
+				`prosopo-challenge-surface--${isFloating ? "float" : "popup"}`,
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+			style={layerStyle}
+		>
+			<div
+				ref={contentRef}
+				className={
+					popupIosLift && !isFloating
+						? "prosopo-challenge-content prosopo-challenge-content--ios-lift"
+						: "prosopo-challenge-content"
+				}
+				style={contentStyle}
+			>
+				{children}
+			</div>
+		</div>,
+		document.body,
+	);
+});
+
+ChallengeSurface.displayName = "ChallengeSurface";
+
+export { ChallengeSurface, computeFloatPosition };

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

@@ -0,0 +1,104 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, it } from "vitest";
+import { computeFloatPosition } from "../reactComponents/ChallengeSurface.js";
+
+const VIEWPORT_WIDTH = 1000;
+const VIEWPORT_HEIGHT = 800;
+
+// jsdom gives every element a zero rect, so rects are built by hand.
+const rect = (
+	left: number,
+	top: number,
+	width: number,
+	height: number,
+): DOMRect =>
+	({
+		left,
+		top,
+		width,
+		height,
+		right: left + width,
+		bottom: top + height,
+		x: left,
+		y: top,
+		toJSON: () => ({}),
+	}) as DOMRect;
+
+const PANEL_HEIGHT = 250;
+
+const place = (
+	anchor: DOMRect,
+	panelHeight = PANEL_HEIGHT,
+	scrollX = 0,
+	scrollY = 0,
+) => computeFloatPosition(anchor, panelHeight, scrollX, scrollY);
+
+describe("computeFloatPosition", () => {
+	it("sits directly above the anchor", () => {
+		const anchor = rect(100, 300, 300, 78);
+
+		const { top, left } = place(anchor);
+
+		expect(top).toBe(anchor.top - PANEL_HEIGHT - 8);
+		expect(left).toBe(anchor.left);
+	});
+
+	it("stays above the anchor even when the space below is larger", () => {
+		// Plenty of room below, none of which should tempt it downwards.
+		const anchor = rect(100, 400, 300, 50);
+
+		const { top } = place(anchor);
+
+		expect(top).toBe(anchor.top - PANEL_HEIGHT - 8);
+		expect(top + PANEL_HEIGHT).toBeLessThan(anchor.top);
+	});
+
+	it("converts the viewport rect into document coordinates", () => {
+		const anchor = rect(100, 300, 300, 78);
+
+		const { top, left } = place(anchor, PANEL_HEIGHT, 40, 500);
+
+		expect(top).toBe(anchor.top + 500 - PANEL_HEIGHT - 8);
+		expect(left).toBe(anchor.left + 40);
+	});
+
+	it("does not move when only the scroll offset changes", () => {
+		// The same widget, seen after scrolling 200px: its viewport rect moves
+		// up by exactly what the scroll offset gains, so the document position
+		// is unchanged and the panel does not drift.
+		const unscrolled = place(rect(100, 300, 300, 78), PANEL_HEIGHT, 0, 0);
+		const scrolled = place(rect(100, 100, 300, 78), PANEL_HEIGHT, 0, 200);
+
+		expect(scrolled).toEqual(unscrolled);
+	});
+
+	it("tracks a taller panel so its bottom edge stays on the anchor", () => {
+		const anchor = rect(100, 600, 300, 78);
+
+		const short = place(anchor, 100);
+		const tall = place(anchor, 400);
+
+		expect(short.top + 100).toBe(tall.top + 400);
+	});
+
+	it("clamps to the top of the document rather than going out of reach", () => {
+		const anchor = rect(100, 20, 300, 78);
+
+		const { top } = place(anchor, PANEL_HEIGHT);
+
+		expect(top).toBe(0);
+	});
+});

package/src/tests/challengeSurfaceRender.unit.test.tsx

@@ -0,0 +1,207 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// jsdom has no PointerEvent; the dismiss handler only reads event.target, so
+// a plain Event of the same type is dispatched instead.
+import { PlacementEnum, type PlacementType } from "@prosopo/types";
+import { type Root, createRoot } from "react-dom/client";
+import { act } from "react-dom/test-utils";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ChallengeSurface } from "../reactComponents/ChallengeSurface.js";
+
+let container: HTMLDivElement;
+let root: Root;
+let anchor: HTMLDivElement;
+
+const layer = (): HTMLElement | null =>
+	document.querySelector<HTMLElement>(".prosopo-challenge-surface");
+
+const content = (): HTMLElement | null =>
+	document.querySelector<HTMLElement>(".prosopo-challenge-content");
+
+interface RenderArgs {
+	placement?: PlacementType;
+	withAnchor?: boolean;
+	onDismiss?: () => void;
+	show?: boolean;
+}
+
+const render = ({
+	placement,
+	withAnchor = true,
+	onDismiss,
+	show = true,
+}: RenderArgs): void => {
+	act(() => {
+		root.render(
+			<ChallengeSurface
+				show={show}
+				placement={placement}
+				anchor={withAnchor ? anchor : null}
+				onDismiss={onDismiss}
+			>
+				<div data-testid="challenge">challenge</div>
+			</ChallengeSurface>,
+		);
+	});
+};
+
+beforeEach(() => {
+	container = document.createElement("div");
+	anchor = document.createElement("div");
+	document.body.append(container, anchor);
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => root.unmount());
+	container.remove();
+	anchor.remove();
+});
+
+describe("where the surface renders", () => {
+	it("portals out of the mount container to the body", () => {
+		render({});
+
+		expect(container.querySelector(".prosopo-challenge-surface")).toBeNull();
+		expect(layer()?.parentElement).toBe(document.body);
+	});
+
+	it("hides rather than unmounts when not shown", () => {
+		render({ show: false });
+
+		expect(layer()?.style.display).toBe("none");
+		expect(layer()?.textContent).toContain("challenge");
+	});
+});
+
+describe("popup", () => {
+	it("is the default placement", () => {
+		render({});
+
+		expect(layer()?.className).toContain("prosopo-challenge-surface--popup");
+	});
+
+	it("covers the page, so nothing behind it is reachable", () => {
+		render({ placement: PlacementEnum.popup });
+
+		expect(layer()?.style.display).toBe("flex");
+		expect(layer()?.style.pointerEvents).toBe("");
+	});
+
+	it("ignores an outside click", () => {
+		const onDismiss = vi.fn();
+		render({ placement: PlacementEnum.popup, onDismiss });
+
+		act(() => {
+			document.body.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+		});
+
+		expect(onDismiss).not.toHaveBeenCalled();
+	});
+});
+
+describe("float", () => {
+	it("leaves the page usable behind it", () => {
+		render({ placement: PlacementEnum.float });
+
+		expect(layer()?.className).toContain("prosopo-challenge-surface--float");
+		expect(layer()?.style.pointerEvents).toBe("none");
+		expect(content()?.style.pointerEvents).toBe("auto");
+	});
+
+	it("positions the panel absolutely so the page scrolls it", () => {
+		render({ placement: PlacementEnum.float });
+
+		// Viewport-relative positioning is what made the panel drift while
+		// scrolling; document-relative is what keeps it still.
+		expect(content()?.style.position).toBe("absolute");
+		expect(layer()?.style.position).toBe("absolute");
+		expect(layer()?.style.width).toBe("0px");
+		expect(layer()?.style.height).toBe("0px");
+	});
+
+	it("dismisses on a click outside the panel", () => {
+		const onDismiss = vi.fn();
+		render({ placement: PlacementEnum.float, onDismiss });
+
+		act(() => {
+			document.body.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+		});
+
+		expect(onDismiss).toHaveBeenCalledTimes(1);
+	});
+
+	it("does not dismiss on a click inside the panel", () => {
+		const onDismiss = vi.fn();
+		render({ placement: PlacementEnum.float, onDismiss });
+
+		act(() => {
+			content()?.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+		});
+
+		expect(onDismiss).not.toHaveBeenCalled();
+	});
+
+	it("does not dismiss on a click on the anchor", () => {
+		const onDismiss = vi.fn();
+		render({ placement: PlacementEnum.float, onDismiss });
+
+		act(() => {
+			anchor.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+		});
+
+		expect(onDismiss).not.toHaveBeenCalled();
+	});
+
+	it("falls back to popup with no anchor to attach to", () => {
+		render({ placement: PlacementEnum.float, withAnchor: false });
+
+		expect(layer()?.className).toContain("prosopo-challenge-surface--popup");
+		expect(layer()?.style.pointerEvents).toBe("");
+	});
+});
+
+describe("dismissing with the keyboard", () => {
+	it("closes on Escape in either placement", () => {
+		for (const placement of [PlacementEnum.popup, PlacementEnum.float]) {
+			const onDismiss = vi.fn();
+			render({ placement, onDismiss });
+
+			act(() => {
+				document.dispatchEvent(
+					new KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+				);
+			});
+
+			expect(
+				onDismiss,
+				`${placement} should close on Escape`,
+			).toHaveBeenCalled();
+		}
+	});
+
+	it("ignores other keys", () => {
+		const onDismiss = vi.fn();
+		render({ placement: PlacementEnum.float, onDismiss });
+
+		act(() => {
+			document.dispatchEvent(
+				new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+			);
+		});
+
+		expect(onDismiss).not.toHaveBeenCalled();
+	});
+});