@prosopo/procaptcha-bundle 4.3.0 → 4.4.1

package/src/index.ts

@@ -24,7 +24,7 @@ import { at } from "@prosopo/util";
 import type { Root } from "react-dom/client";
 import { extractParams, getProcaptchaScript } from "./util/config.js";
 import { resolveStartMode } from "./util/startMode.js";
-import { WidgetFactory } from "./util/widgetFactory.js";
+import { type CreatedWidget, WidgetFactory } from "./util/widgetFactory.js";
 import { WidgetThemeResolver } from "./util/widgetThemeResolver.js";
 
 const BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
@@ -43,9 +43,12 @@ const BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
 interface WidgetEntry {
 	root: Root;
 	element: Element;
+	/** The element the widget listens on; a targeted execute() is dispatched here. */
+	target: HTMLElement;
 	renderOptions: ProcaptchaRenderOptions;
 	isWeb2: boolean;
 	invisible: boolean;
+	unbindTrigger?: () => void;
 }
 
 const procaptchaWidgets = new Map<string, WidgetEntry>();
@@ -54,17 +57,18 @@ let widgetIdCounter = 0;
 const nextWidgetId = (): string => `procaptcha-widget-${widgetIdCounter++}`;
 
 const registerWidgets = (
-	roots: Root[],
+	widgets: CreatedWidget[],
 	elements: Element[],
 	renderOptions: ProcaptchaRenderOptions,
 	isWeb2: boolean,
 	invisible: boolean,
 ): string[] =>
-	roots.map((root, index) => {
+	widgets.map(({ root, container }, index) => {
 		const id = nextWidgetId();
 		procaptchaWidgets.set(id, {
 			root,
 			element: at(elements, index),
+			target: container,
 			renderOptions,
 			isWeb2,
 			invisible,
@@ -145,19 +149,26 @@ const implicitRender = async () => {
 			startMode,
 		};
 
-		const root = await widgetFactory.createWidgets(
+		const widgets = await widgetFactory.createWidgets(
 			elements,
 			implicitRenderOptions,
 			!(web3 === "true"),
 		);
 
-		registerWidgets(
-			root,
+		const ids = registerWidgets(
+			widgets,
 			elements,
 			implicitRenderOptions,
 			!(web3 === "true"),
 			false,
 		);
+
+		// `data-placement` is read per element by the renderer; `data-bind` is
+		// wired here because the trigger lives outside the widget.
+		ids.forEach((id, index) => {
+			const selector = at(elements, index).getAttribute("data-bind");
+			if (selector) bindTrigger(id, selector);
+		});
 	}
 
 	// Check for invisible mode indicators (procaptcha class on buttons)
@@ -183,19 +194,25 @@ const implicitRender = async () => {
 				startMode,
 			};
 
-			const root = await widgetFactory.createWidgets(
+			const widgets = await widgetFactory.createWidgets(
 				[button],
 				buttonRenderOptions,
 				true,
 				true,
 			);
 
-			registerWidgets(root, [button], buttonRenderOptions, true, true);
+			const [id] = registerWidgets(
+				widgets,
+				[button],
+				buttonRenderOptions,
+				true,
+				true,
+			);
 
 			// Add click event listener to the button
 			button.addEventListener("click", async (event) => {
 				event.preventDefault();
-				execute();
+				execute(id);
 			});
 		}
 	}
@@ -228,7 +245,7 @@ export const render = async (
 	const invisible =
 		hasInvisibleSize || element.tagName.toLowerCase() === "button";
 
-	const roots = await widgetFactory.createWidgets(
+	const widgets = await widgetFactory.createWidgets(
 		[element],
 		renderOptions,
 		isWeb2,
@@ -236,7 +253,7 @@ export const render = async (
 	);
 
 	const ids = registerWidgets(
-		roots,
+		widgets,
 		[element],
 		renderOptions,
 		isWeb2,
@@ -245,7 +262,10 @@ export const render = async (
 
 	// Deliberately not `at()`: it throws on an empty array before it consults
 	// `optional`, and zero roots is a legitimate outcome here.
-	return ids[0];
+	const id = ids[0];
+	if (id && renderOptions.bind) bindTrigger(id, renderOptions.bind);
+
+	return id;
 };
 
 export default function ready(fn: () => void) {
@@ -262,8 +282,21 @@ export default function ready(fn: () => void) {
 	}
 }
 
-export const execute = () => {
-	const containers = findProcaptchaContainers();
+/**
+ * Starts verification. With no id the event goes to `document` and every
+ * widget responds; with an id (as returned by `render()`) only that widget
+ * runs.
+ */
+export const execute = (widgetId?: string) => {
+	const targeted =
+		undefined === widgetId ? undefined : procaptchaWidgets.get(widgetId);
+
+	if (undefined !== widgetId && !targeted) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+
+	const containers = targeted ? [targeted.element] : findProcaptchaContainers();
 
 	if (containers.length === 0) {
 		console.error("No Procaptcha containers found for execution");
@@ -277,14 +310,50 @@ export const execute = () => {
 			containerCount: containers.length,
 			timestamp: Date.now(),
 		},
-		bubbles: true,
+		// A targeted event must not bubble to document, where every widget listens.
+		bubbles: !targeted,
 		cancelable: true,
 	});
 
+	if (targeted) {
+		targeted.target.dispatchEvent(executeEvent);
+		return;
+	}
+
 	// Dispatch the event on the document
 	document.dispatchEvent(executeEvent);
 };
 
+/**
+ * The click's default is prevented so a submit button does not post the form
+ * before a token exists.
+ */
+const bindTrigger = (widgetId: string, selector: string): void => {
+	const entry = procaptchaWidgets.get(widgetId);
+	if (!entry) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+
+	const trigger = document.querySelector(selector);
+	if (!trigger) {
+		console.error(`Procaptcha: no element matches bind selector ${selector}`);
+		return;
+	}
+
+	// Binding the same widget twice would otherwise stack listeners and leave
+	// the earlier one behind, since only the last unbind is remembered.
+	entry.unbindTrigger?.();
+
+	const onClick = (event: Event) => {
+		event.preventDefault();
+		execute(widgetId);
+	};
+
+	trigger.addEventListener("click", onClick);
+	entry.unbindTrigger = () => trigger.removeEventListener("click", onClick);
+};
+
 /** Starts a `startMode: "manual"` widget; omit the id to start all of them. */
 export const start = (widgetId?: string): void => {
 	const ids: string[] =
@@ -417,15 +486,19 @@ export const reset = async (widgetId?: string): Promise<void> => {
 
 		current.root.unmount();
 
-		const [root] = await widgetFactory.createWidgets(
+		const [widget] = await widgetFactory.createWidgets(
 			[current.element],
 			current.renderOptions,
 			current.isWeb2,
 			current.invisible,
 		);
 
-		if (root) {
-			procaptchaWidgets.set(id, { ...current, root });
+		if (widget) {
+			procaptchaWidgets.set(id, {
+				...current,
+				root: widget.root,
+				target: widget.container,
+			});
 		} else {
 			procaptchaWidgets.delete(id);
 		}
@@ -445,6 +518,7 @@ export const remove = (widgetId?: string): void => {
 	for (const id of ids) {
 		const entry = procaptchaWidgets.get(id);
 		if (!entry) continue;
+		entry.unbindTrigger?.();
 		entry.root.unmount();
 		entry.element.innerHTML = "";
 		procaptchaWidgets.delete(id);

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

@@ -0,0 +1,227 @@
+// 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 type { Root } from "react-dom/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
+
+const mocks = vi.hoisted(() => ({
+	prefetchDetector: vi.fn(),
+	createWidgets: vi.fn(),
+}));
+
+vi.mock("@prosopo/procaptcha-frictionless", () => ({
+	prefetchDetector: mocks.prefetchDetector,
+}));
+
+vi.mock("@prosopo/procaptcha-common", () => ({
+	getWindowCallback: vi.fn(),
+	pickIpMode: vi.fn(() => undefined),
+}));
+
+vi.mock("../util/widgetFactory.js", () => ({
+	WidgetFactory: vi.fn(function () {
+		return { createWidgets: mocks.createWidgets };
+	}),
+}));
+
+const { render, remove, execute } = await import("../index.js");
+
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+const EXECUTE_EVENT = "procaptcha:execute";
+
+const makeRoot = (): Root =>
+	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
+
+// Like the real factory, the widget lives in a child of the host element and
+// listens there, so a targeted event must be dispatched on that child.
+const createWidgetsLikeTheFactory = async (
+	hosts: Element[],
+): Promise<CreatedWidget[]> =>
+	hosts.map((host) => {
+		const container = document.createElement("div");
+		host.appendChild(container);
+		return { root: makeRoot(), container };
+	});
+
+const listenLikeAWidget = (
+	host: Element,
+): { calls: () => number; stop: () => void } => {
+	const handler = vi.fn();
+	const target = host.firstElementChild;
+	if (!target) throw new Error("expected the factory to mount a container");
+	document.addEventListener(EXECUTE_EVENT, handler);
+	target.addEventListener(EXECUTE_EVENT, handler);
+	return {
+		calls: () => handler.mock.calls.length,
+		stop: () => {
+			document.removeEventListener(EXECUTE_EVENT, handler);
+			target.removeEventListener(EXECUTE_EVENT, handler);
+		},
+	};
+};
+
+beforeEach(async () => {
+	vi.clearAllMocks();
+	await remove();
+	document.body.innerHTML = "";
+	mocks.createWidgets.mockImplementation(createWidgetsLikeTheFactory);
+});
+
+describe("execute targeting", () => {
+	it("reaches every widget when called with no id", async () => {
+		const first = document.createElement("div");
+		first.className = "p-procaptcha";
+		const second = document.createElement("div");
+		second.className = "p-procaptcha";
+		document.body.append(first, second);
+		await render(first, { siteKey: SITE_KEY });
+		await render(second, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(first);
+		const b = listenLikeAWidget(second);
+		execute();
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(1);
+		a.stop();
+		b.stop();
+	});
+
+	it("reaches only the named widget when given an id", async () => {
+		const first = document.createElement("div");
+		const second = document.createElement("div");
+		document.body.append(first, second);
+		const firstId = await render(first, { siteKey: SITE_KEY });
+		await render(second, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(first);
+		const b = listenLikeAWidget(second);
+		execute(firstId);
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(0);
+		a.stop();
+		b.stop();
+	});
+
+	it("does not bubble a targeted event up to document", async () => {
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+		const widgetId = await render(element, { siteKey: SITE_KEY });
+
+		const documentOnly = vi.fn();
+		document.addEventListener(EXECUTE_EVENT, documentOnly);
+		execute(widgetId);
+
+		expect(documentOnly).not.toHaveBeenCalled();
+		document.removeEventListener(EXECUTE_EVENT, documentOnly);
+	});
+
+	it("reports an unknown id rather than firing every widget", async () => {
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+		await render(element, { siteKey: SITE_KEY });
+
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		const listener = listenLikeAWidget(element);
+		execute("procaptcha-widget-does-not-exist");
+
+		expect(listener.calls()).toBe(0);
+		expect(error).toHaveBeenCalled();
+		listener.stop();
+		error.mockRestore();
+	});
+});
+
+describe("bind", () => {
+	it("runs only the bound widget when its button is clicked", async () => {
+		const button = document.createElement("button");
+		button.id = "pay";
+		const bound = document.createElement("div");
+		const other = document.createElement("div");
+		document.body.append(button, bound, other);
+
+		await render(bound, { siteKey: SITE_KEY, bind: "#pay" });
+		await render(other, { siteKey: SITE_KEY });
+
+		const a = listenLikeAWidget(bound);
+		const b = listenLikeAWidget(other);
+		button.click();
+
+		expect(a.calls()).toBe(1);
+		expect(b.calls()).toBe(0);
+		a.stop();
+		b.stop();
+	});
+
+	it("stops the button's default action", async () => {
+		const form = document.createElement("form");
+		const button = document.createElement("button");
+		button.id = "submit-it";
+		button.type = "submit";
+		form.appendChild(button);
+		const element = document.createElement("div");
+		document.body.append(form, element);
+
+		await render(element, { siteKey: SITE_KEY, bind: "#submit-it" });
+
+		const event = new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+		});
+		button.dispatchEvent(event);
+
+		expect(event.defaultPrevented).toBe(true);
+	});
+
+	it("detaches the listener when the widget is removed", async () => {
+		const button = document.createElement("button");
+		button.id = "gone";
+		const element = document.createElement("div");
+		document.body.append(button, element);
+
+		await render(element, { siteKey: SITE_KEY, bind: "#gone" });
+		await remove();
+
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		button.click();
+
+		expect(error).not.toHaveBeenCalled();
+		error.mockRestore();
+	});
+
+	it("reports a selector that matches nothing and still renders", async () => {
+		const error = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined);
+		const element = document.createElement("div");
+		document.body.appendChild(element);
+
+		const widgetId = await render(element, {
+			siteKey: SITE_KEY,
+			bind: "#nothing-here",
+		});
+
+		expect(widgetId).toBeTruthy();
+		expect(error).toHaveBeenCalledWith(
+			expect.stringContaining("#nothing-here"),
+		);
+		error.mockRestore();
+	});
+});

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

@@ -19,8 +19,8 @@
  * to assigning a detector inline on the widget's critical path.
  */
 
-import type { Root } from "react-dom/client";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
 
 const mocks = vi.hoisted(() => ({
 	prefetchDetector: vi.fn(),
@@ -59,7 +59,7 @@ const renderAndFlush = async (
 
 beforeEach(() => {
 	vi.clearAllMocks();
-	mocks.createWidgets.mockResolvedValue([] as Root[]);
+	mocks.createWidgets.mockResolvedValue([] as CreatedWidget[]);
 });
 
 describe("render", () => {

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

@@ -22,6 +22,7 @@
 
 import type { Root } from "react-dom/client";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
 
 const mocks = vi.hoisted(() => ({
 	prefetchDetector: vi.fn(),
@@ -50,10 +51,15 @@ const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
 const makeRoot = (): Root =>
 	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
 
+const makeWidget = (root: Root = makeRoot()): CreatedWidget => ({
+	root,
+	container: document.createElement("div"),
+});
+
 /** Each createWidgets call yields a distinct root, as the real factory does. */
 const queueRoots = (...roots: Root[]): void => {
 	for (const root of roots) {
-		mocks.createWidgets.mockResolvedValueOnce([root]);
+		mocks.createWidgets.mockResolvedValueOnce([makeWidget(root)]);
 	}
 };
 
@@ -62,7 +68,7 @@ beforeEach(async () => {
 	// Drop any widgets registered by a previous test — module state persists
 	// across tests in the same file.
 	await remove();
-	mocks.createWidgets.mockResolvedValue([makeRoot()]);
+	mocks.createWidgets.mockResolvedValue([makeWidget()]);
 });
 
 describe("render", () => {
@@ -78,7 +84,7 @@ describe("render", () => {
 	});
 
 	it("returns undefined when the factory creates no widget", async () => {
-		mocks.createWidgets.mockResolvedValueOnce([] as Root[]);
+		mocks.createWidgets.mockResolvedValueOnce([] as CreatedWidget[]);
 
 		const widgetId = await render(document.createElement("div"), {
 			siteKey: SITE_KEY,

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

@@ -19,6 +19,7 @@ import {
 } from "@prosopo/types";
 import type { Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CreatedWidget } from "../util/widgetFactory.js";
 
 const mocks = vi.hoisted(() => ({
 	prefetchDetector: vi.fn(),
@@ -44,8 +45,10 @@ const { render, remove, start } = await import("../index.js");
 
 const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
 
-const makeRoot = (): Root =>
-	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
+const makeWidget = (): CreatedWidget => ({
+	root: { unmount: vi.fn(), render: vi.fn() } as unknown as Root,
+	container: document.createElement("div"),
+});
 
 const flush = (): Promise<void> =>
 	new Promise((resolve) => setTimeout(resolve, 0));
@@ -53,7 +56,7 @@ const flush = (): Promise<void> =>
 const renderWidget = async (
 	options: Partial<Parameters<typeof render>[1]> = {},
 ): Promise<{ element: HTMLDivElement; id: string }> => {
-	mocks.createWidgets.mockResolvedValueOnce([makeRoot()]);
+	mocks.createWidgets.mockResolvedValueOnce([makeWidget()]);
 	const element = document.createElement("div");
 	const id = await render(element, { siteKey: SITE_KEY, ...options });
 	if (!id) throw new Error("expected render to return a widget id");
@@ -141,7 +144,7 @@ describe("detector prefetch", () => {
 	});
 
 	it("is skipped when the element asks for manual mode", async () => {
-		mocks.createWidgets.mockResolvedValueOnce([makeRoot()]);
+		mocks.createWidgets.mockResolvedValueOnce([makeWidget()]);
 		const element = document.createElement("div");
 		element.setAttribute("data-start-mode", "manual");
 		await render(element, { siteKey: SITE_KEY });

package/src/util/captcha/captchaRenderer.tsx

@@ -15,10 +15,12 @@
 import createCache, { type EmotionCache } from "@emotion/cache";
 import { CacheProvider } from "@emotion/react";
 import type { Ti18n } from "@prosopo/locale";
-import type {
-	Callbacks,
-	ProcaptchaClientConfigOutput,
-	ProcaptchaRenderOptions,
+import {
+	type Callbacks,
+	Placement,
+	type PlacementType,
+	type ProcaptchaClientConfigOutput,
+	type ProcaptchaRenderOptions,
 } from "@prosopo/types";
 import type { ReactNode } from "react";
 import { type Root, createRoot } from "react-dom/client";
@@ -29,6 +31,18 @@ import { setStartMode } from "../startMode.js";
 import { setValidChallengeLength } from "../timeout.js";
 import { BundleCaptcha } from "./components/bundleCaptcha.js";
 
+const resolveRequestedPlacement = (
+	element: Element,
+	renderOptions: ProcaptchaRenderOptions,
+): PlacementType | undefined => {
+	const requested =
+		renderOptions.placement ?? element.getAttribute("data-placement");
+	if (!requested) return undefined;
+
+	const parsed = Placement.safeParse(requested);
+	return parsed.success ? parsed.data : undefined;
+};
+
 interface RenderSettings {
 	identifierPrefix: string;
 	emotionCacheKey: string;
@@ -47,16 +61,20 @@ class CaptchaRenderer {
 		widgetContainer: HTMLElement,
 		sourceElement?: Element,
 	): Root {
-		const config = createConfig(
-			renderOptions.siteKey,
-			renderOptions.theme,
-			renderOptions.language,
-			isWeb2,
+		const config = createConfig({
+			siteKey: renderOptions.siteKey,
+			theme: renderOptions.theme,
+			language: renderOptions.language,
+			web2: isWeb2,
 			invisible,
-			renderOptions.userAccountAddress,
-			renderOptions.ipv4,
-			renderOptions.ipv6,
-		);
+			placement: resolveRequestedPlacement(
+				sourceElement || container,
+				renderOptions,
+			),
+			userAccountAddress: renderOptions.userAccountAddress,
+			ipv4: renderOptions.ipv4,
+			ipv6: renderOptions.ipv6,
+		});
 		this.readAndValidateSettings(
 			sourceElement || container,
 			config,

package/src/util/configCreator.ts

@@ -15,23 +15,39 @@
 import type { Languages } from "@prosopo/locale";
 import {
 	EnvironmentTypesSchema,
+	type PlacementType,
 	type ProcaptchaClientConfigOutput,
 	ProcaptchaConfigSchema,
+	resolvePlacement,
 } from "@prosopo/types";
 
+interface CreateConfigOptions {
+	siteKey?: string;
+	theme?: "light" | "dark";
+	language?: (typeof Languages)[keyof typeof Languages];
+	web2?: boolean;
+	invisible?: boolean;
+	placement?: PlacementType;
+	userAccountAddress?: string;
+	ipv4?: boolean;
+	ipv6?: boolean;
+}
+
 function createConfig(
-	siteKey?: string,
-	theme: "light" | "dark" = "light",
-	language?: (typeof Languages)[keyof typeof Languages],
-	web2 = true,
-	invisible = false,
-	userAccountAddress?: string,
-	ipv4 = false,
-	ipv6 = false,
+	options: CreateConfigOptions = {},
 ): ProcaptchaClientConfigOutput {
-	if (!siteKey) {
-		siteKey = process.env.PROSOPO_SITE_KEY || "";
-	}
+	const {
+		theme = "light",
+		language,
+		web2 = true,
+		invisible = false,
+		placement,
+		userAccountAddress,
+		ipv4 = false,
+		ipv6 = false,
+	} = options;
+
+	const siteKey = options.siteKey || process.env.PROSOPO_SITE_KEY || "";
 
 	return ProcaptchaConfigSchema.parse({
 		defaultEnvironment: process.env.PROSOPO_DEFAULT_ENVIRONMENT
@@ -45,6 +61,7 @@ function createConfig(
 		mongoAtlasUri: process.env.PROSOPO_MONGO_EVENTS_URI || "",
 		web2,
 		mode: invisible ? "invisible" : "visible",
+		placement: resolvePlacement(placement, invisible),
 		theme,
 		language,
 		ipv4,
@@ -53,3 +70,4 @@ function createConfig(
 }
 
 export { createConfig };
+export type { CreateConfigOptions };