@rozie-ui/captcha-react 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Krieger and Rozie.js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @rozie-ui/captcha-react
+
+Idiomatic **react** `Captcha` — Cross-framework CAPTCHA / bot-protection widget wrapping Google reCAPTCHA v2, hCaptcha, and Cloudflare Turnstile. Compiled from one [Rozie](https://github.com/One-Learning-Community/rozie.js) source. This package is generated; do not edit `src/` by hand.
+
+This package ships `Captcha` (the default export) alongside `RecaptchaV3` (named export).
+
+## Install
+
+```bash
+npm i @rozie-ui/captcha-react
+```
+
+Peer dependencies: `react + react-dom`.
+
+## Captcha
+
+### Usage
+
+```tsx
+import { useState } from 'react';
+import { Captcha } from '@rozie-ui/captcha-react';
+
+export function Demo() {
+  const [token, setToken] = useState('');
+  return (
+    <Captcha
+      provider="recaptcha"
+      sitekey="your-site-key"
+      token={token}
+      onTokenChange={setToken}
+      onVerify={(e) => console.log('verified', e.token)}
+    />
+  );
+}
+```
+
+### Props
+
+| Name | Type | Default | Two-way (model) | Required |
+| --- | --- | --- | :---: | :---: |
+| `provider` | `String` | `"recaptcha"` |  |  |
+| `sitekey` | `String` | `—` |  | ✓ |
+| `token` | `String` | `""` | ✓ |  |
+| `theme` | `String` | `"light"` |  |  |
+| `size` | `String` | `"normal"` |  |  |
+| `tabindex` | `Number` | `null` |  |  |
+| `options` | `Object` | `{}` |  |  |
+
+### Events
+
+| Event | Description |
+| --- | --- |
+| `verify` | Fired when the user completes the challenge. Payload `{ token, provider }`. |
+| `expire` | Fired when the verified token expires. Payload `{ provider }`. |
+| `error` | Fired on a challenge or script-load failure. Payload `{ provider, error? }`. |
+
+### Imperative handle
+
+This component exposes imperative methods (declared once in the Rozie source via `$expose`). Grab a handle with the native ref mechanism and call them directly:
+
+```tsx
+import { useRef } from 'react';
+import { Captcha, type CaptchaHandle } from '@rozie-ui/captcha-react';
+
+const handle = useRef<CaptchaHandle>(null);
+// <Captcha ref={handle} provider="recaptcha" sitekey="your-site-key" />
+// handle.current?.reset();        // clear + reset the widget
+// handle.current?.execute();      // invisible / programmatic challenge
+// handle.current?.getResponse();  // read the current token
+```
+
+| Method | Description |
+| --- | --- |
+| `reset` | Reset the widget to its un-challenged state and clear the two-way `token`. |
+| `execute` | Programmatically run the challenge — drives invisible widgets (`size="invisible"`). |
+| `getResponse` | Return the current response token on demand (e.g. just before form submit). |
+
+## RecaptchaV3
+
+### Usage
+
+```tsx
+import { useRef } from 'react';
+import { RecaptchaV3, type RecaptchaV3Handle } from '@rozie-ui/captcha-react';
+
+export function SignupForm() {
+  const captcha = useRef<RecaptchaV3Handle>(null);
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const token = await captcha.current?.execute('signup'); // fresh token for THIS action
+    await fetch('/signup', { method: 'POST', body: JSON.stringify({ token }) });
+  };
+  return (
+    <form onSubmit={onSubmit}>
+      {/* … fields … */}
+      <RecaptchaV3 ref={captcha} sitekey="your-site-key" action="signup" />
+      <button type="submit">Sign up</button>
+    </form>
+  );
+}
+```
+
+### Props
+
+| Name | Type | Default | Two-way (model) | Required |
+| --- | --- | --- | :---: | :---: |
+| `sitekey` | `String` | `—` |  | ✓ |
+| `action` | `String` | `"submit"` |  |  |
+| `token` | `String` | `""` | ✓ |  |
+| `executeOnMount` | `Boolean` | `false` |  |  |
+
+### Events
+
+| Event | Description |
+| --- | --- |
+| `error` | Fired on a load timeout, script error, or a rejected `execute()`. Payload `{ error? }`. |
+| `verify` | Fired on a successful `execute()`. Payload `{ token, action }`. |
+
+### Imperative handle
+
+This component exposes imperative methods (declared once in the Rozie source via `$expose`). Grab a handle with the native ref mechanism and call them directly:
+
+```tsx
+import { useRef } from 'react';
+import { RecaptchaV3, type RecaptchaV3Handle } from '@rozie-ui/captcha-react';
+
+const handle = useRef<RecaptchaV3Handle>(null);
+// <RecaptchaV3 ref={handle} sitekey="your-site-key" action="submit" />
+// const token = await handle.current?.execute();          // uses the action prop
+// const token = await handle.current?.execute('login');   // override for this call
+```
+
+| Method | Description |
+| --- | --- |
+| `execute` | Run a v3 challenge for the optional `action` (defaults to the `action` prop) and resolve with a fresh token; also writes the two-way `token` and emits `@verify`. |

package/dist/index.cjs

@@ -0,0 +1,359 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let react = require("react");
+let _rozie_runtime_react = require("@rozie/runtime-react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/internal/loadCaptchaApi.ts
+/**
+* Bridge Friendly Captcha's `createWidget` SDK (the `@friendlycaptcha/sdk`
+* compat build, loaded from the CDN — NO npm peer dependency) onto `CaptchaApi`.
+*
+* FC has no explicit-`render`/widget-id model: `createWidget({ element, ... })`
+* returns an event-emitter handle (`frc:widget.complete|expire|error`) with
+* `reset()` / `start()` / `getResponse()` / `destroy()`. We treat that handle AS
+* the opaque widget id the rest of the family already threads around. FC also
+* has no `size` concept — `startMode` is the closest analog and rides through
+* the `options` escape hatch (or a `startMode` config key if a consumer passes
+* one directly).
+*/
+const adaptFriendly = (g) => {
+	const fc = g;
+	return {
+		render(el, cfg) {
+			const h = fc.createWidget({
+				element: el,
+				sitekey: cfg.sitekey,
+				theme: cfg.theme,
+				startMode: cfg.startMode
+			});
+			h.addEventListener("frc:widget.complete", (e) => {
+				const cb = cfg.callback;
+				if (typeof cb === "function") cb(e.detail?.response ?? "");
+			});
+			h.addEventListener("frc:widget.expire", () => {
+				const cb = cfg["expired-callback"];
+				if (typeof cb === "function") cb();
+			});
+			h.addEventListener("frc:widget.error", () => {
+				const cb = cfg["error-callback"];
+				if (typeof cb === "function") cb();
+			});
+			return h;
+		},
+		reset: (id) => id.reset(),
+		execute: (id) => id.start(),
+		getResponse: (id) => id.getResponse(),
+		remove: (id) => id.destroy()
+	};
+};
+const CAPTCHA_PROVIDERS = {
+	recaptcha: {
+		src: "https://www.google.com/recaptcha/api.js?render=explicit",
+		global: "grecaptcha"
+	},
+	hcaptcha: {
+		src: "https://js.hcaptcha.com/1/api.js?render=explicit",
+		global: "hcaptcha"
+	},
+	turnstile: {
+		src: "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit",
+		global: "turnstile"
+	},
+	friendly: {
+		src: "https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@1/site.compat.min.js",
+		global: "frcaptcha",
+		adapt: adaptFriendly
+	}
+};
+/**
+* Load a provider's api.js ONCE across the whole document, shared by every
+* `<Captcha>` instance via a `globalThis` singleton (a per-instance cache would
+* re-inject per component). Resolves with the provider global once its
+* `render()` is callable; rejects on an unknown provider, a script load error,
+* or a `LOAD_TIMEOUT_MS` timeout. `providers` is injectable for tests.
+*/
+function loadCaptchaApi(provider, providers = CAPTCHA_PROVIDERS) {
+	const cfg = providers[provider];
+	if (!cfg) return Promise.reject(/* @__PURE__ */ new Error("Unknown captcha provider: " + provider));
+	const root = globalThis;
+	const cache = root.__rozieCaptchaLoaders ||= {};
+	if (cache[provider]) return cache[provider];
+	const win = globalThis;
+	const ready = (g) => {
+		if (!g) return false;
+		const o = g;
+		return typeof o.render === "function" || typeof o.createWidget === "function";
+	};
+	const resolveApi = (g) => cfg.adapt ? cfg.adapt(g) : g;
+	const p = new Promise((resolve, reject) => {
+		if (ready(win[cfg.global])) {
+			resolve(resolveApi(win[cfg.global]));
+			return;
+		}
+		if (!document.querySelector("script[data-rozie-captcha=\"" + provider + "\"]")) {
+			const el = document.createElement("script");
+			el.src = cfg.src;
+			el.async = true;
+			el.defer = true;
+			el.setAttribute("data-rozie-captcha", provider);
+			el.addEventListener("error", () => reject(/* @__PURE__ */ new Error("Failed to load " + provider + " script")));
+			document.head.appendChild(el);
+		}
+		const started = Date.now();
+		const poll = setInterval(() => {
+			if (ready(win[cfg.global])) {
+				clearInterval(poll);
+				resolve(resolveApi(win[cfg.global]));
+			} else if (Date.now() - started > 2e4) {
+				clearInterval(poll);
+				reject(/* @__PURE__ */ new Error(provider + " script load timeout"));
+			}
+		}, 50);
+	});
+	cache[provider] = p;
+	return p;
+}
+//#endregion
+//#region src/Captcha.tsx
+const Captcha = (0, react.forwardRef)(function Captcha(_props, ref) {
+	const __defaultOptions = (0, react.useState)(() => ({}))[0];
+	const props = {
+		..._props,
+		provider: _props.provider ?? "recaptcha",
+		theme: _props.theme ?? "light",
+		size: _props.size ?? "normal",
+		tabindex: _props.tabindex ?? null,
+		options: _props.options ?? __defaultOptions
+	};
+	const attrs = (() => {
+		const { provider, sitekey, token, theme, size, tabindex, options, defaultValue, onTokenChange, defaultToken, ...rest } = _props;
+		return rest;
+	})();
+	const disposed = (0, react.useRef)(false);
+	const api = (0, react.useRef)(null);
+	const widgetId = (0, react.useRef)(null);
+	const [token, setToken] = (0, _rozie_runtime_react.useControllableState)({
+		value: props.token,
+		defaultValue: props.defaultToken ?? "",
+		onValueChange: props.onTokenChange
+	});
+	const widgetEl = (0, react.useRef)(null);
+	const { onError: _rozieProp_onError, onExpire: _rozieProp_onExpire, onVerify: _rozieProp_onVerify } = props;
+	const buildConfig = (0, react.useCallback)(() => ({
+		sitekey: props.sitekey,
+		theme: props.theme,
+		size: props.size,
+		...props.tabindex != null ? { tabindex: props.tabindex } : {},
+		callback: (response) => {
+			setToken(response);
+			_rozieProp_onVerify && _rozieProp_onVerify({
+				token: response,
+				provider: props.provider
+			});
+		},
+		"expired-callback": () => {
+			setToken("");
+			_rozieProp_onExpire && _rozieProp_onExpire({ provider: props.provider });
+		},
+		"error-callback": () => {
+			setToken("");
+			_rozieProp_onError && _rozieProp_onError({ provider: props.provider });
+		},
+		...props.options
+	}), [
+		_rozieProp_onError,
+		_rozieProp_onExpire,
+		_rozieProp_onVerify,
+		props.options,
+		props.provider,
+		props.sitekey,
+		props.size,
+		props.tabindex,
+		props.theme,
+		setToken
+	]);
+	function reset() {
+		if (widgetId.current != null && api.current && typeof api.current.reset === "function") api.current.reset(widgetId.current);
+		setToken("");
+	}
+	function execute() {
+		if (widgetId.current != null && api.current && typeof api.current.execute === "function") api.current.execute(widgetId.current);
+	}
+	function getResponse() {
+		return widgetId.current != null && api.current && typeof api.current.getResponse === "function" ? api.current.getResponse(widgetId.current) : "";
+	}
+	(0, react.useEffect)(() => {
+		disposed.current = false;
+		loadCaptchaApi(props.provider).then((a) => {
+			if (disposed.current) return;
+			api.current = a;
+			widgetId.current = api.current.render(widgetEl.current, buildConfig());
+		}).catch((err) => {
+			props.onError && props.onError({
+				provider: props.provider,
+				error: err
+			});
+		});
+		return () => {
+			disposed.current = true;
+			if (widgetId.current == null || !api.current) return;
+			if (typeof api.current.remove === "function") api.current.remove(widgetId.current);
+			else if (typeof api.current.reset === "function") api.current.reset(widgetId.current);
+		};
+	}, []);
+	const _rozieExposeRef = (0, react.useRef)({
+		reset,
+		execute,
+		getResponse
+	});
+	_rozieExposeRef.current = {
+		reset,
+		execute,
+		getResponse
+	};
+	(0, react.useImperativeHandle)(ref, () => ({
+		reset: (...args) => _rozieExposeRef.current.reset(...args),
+		execute: (...args) => _rozieExposeRef.current.execute(...args),
+		getResponse: (...args) => _rozieExposeRef.current.getResponse(...args)
+	}), []);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		ref: widgetEl,
+		...attrs,
+		className: (0, _rozie_runtime_react.clsx)("rozie-captcha", attrs.className),
+		"data-rozie-s-9c7749d4": ""
+	}) });
+});
+//#endregion
+//#region src/internal/loadRecaptchaV3.ts
+/** The v3 api.js base URL. The sitekey is appended (`render=SITEKEY`) per call. */
+const RECAPTCHA_V3_SRC = "https://www.google.com/recaptcha/api.js?render=";
+const getGrecaptcha = () => globalThis.grecaptcha;
+/**
+* Load reCAPTCHA v3's api.js ONCE per sitekey across the whole document, shared
+* by every `<RecaptchaV3>` instance via a `globalThis` singleton keyed on the
+* sitekey. Resolves with the `grecaptcha` global once `grecaptcha.ready(cb)` has
+* fired; rejects on a script load error or a `LOAD_TIMEOUT_MS` timeout.
+*
+* `srcBase` is injectable for tests (pass `''` so happy-dom does not attempt a
+* real network fetch — mirrors loadCaptchaApi's injectable `providers` seam).
+*/
+function loadRecaptchaV3(sitekey, srcBase = RECAPTCHA_V3_SRC) {
+	const root = globalThis;
+	const cache = root.__rozieRecaptchaV3Loaders ||= {};
+	if (cache[sitekey]) return cache[sitekey];
+	const p = new Promise((resolve, reject) => {
+		let settled = false;
+		const ready = (g) => {
+			g.ready(() => {
+				if (settled) return;
+				settled = true;
+				resolve(g);
+			});
+		};
+		const present = getGrecaptcha();
+		if (present && typeof present.ready === "function") {
+			ready(present);
+			return;
+		}
+		if (!document.querySelector("script[data-rozie-recaptcha-v3=\"" + sitekey + "\"]")) {
+			const el = document.createElement("script");
+			el.src = srcBase + encodeURIComponent(sitekey);
+			el.async = true;
+			el.defer = true;
+			el.setAttribute("data-rozie-recaptcha-v3", sitekey);
+			el.addEventListener("error", () => {
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error("Failed to load reCAPTCHA v3 script for sitekey: " + sitekey));
+			});
+			document.head.appendChild(el);
+		}
+		const started = Date.now();
+		const poll = setInterval(() => {
+			const g = getGrecaptcha();
+			if (g && typeof g.ready === "function") {
+				clearInterval(poll);
+				ready(g);
+			} else if (Date.now() - started > 2e4) {
+				clearInterval(poll);
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error("reCAPTCHA v3 script load timeout for sitekey: " + sitekey));
+			}
+		}, 50);
+	});
+	cache[sitekey] = p;
+	return p;
+}
+/**
+* Run a v3 challenge for `sitekey` + `action`, returning a fresh token.
+* Delegates to `grecaptcha.execute(sitekey, { action })`. Call AFTER
+* `loadRecaptchaV3(sitekey)` has resolved (the component threads that order).
+*/
+function execute(sitekey, opts) {
+	const g = getGrecaptcha();
+	if (!g || typeof g.execute !== "function") return Promise.reject(/* @__PURE__ */ new Error("reCAPTCHA v3 not loaded for sitekey: " + sitekey));
+	return g.execute(sitekey, opts);
+}
+//#endregion
+//#region src/RecaptchaV3.tsx
+const RecaptchaV3 = (0, react.forwardRef)(function RecaptchaV3(_props, ref) {
+	const props = {
+		..._props,
+		action: _props.action ?? "submit",
+		executeOnMount: _props.executeOnMount ?? false
+	};
+	const attrs = (() => {
+		const { sitekey, action, token, executeOnMount, defaultValue, onTokenChange, defaultToken, ...rest } = _props;
+		return rest;
+	})();
+	const disposed = (0, react.useRef)(false);
+	const [token, setToken] = (0, _rozie_runtime_react.useControllableState)({
+		value: props.token,
+		defaultValue: props.defaultToken ?? "",
+		onValueChange: props.onTokenChange
+	});
+	function execute$1(action = null) {
+		const a = action != null ? action : props.action;
+		return loadRecaptchaV3(props.sitekey).then(() => execute(props.sitekey, { action: a })).then((tok) => {
+			if (disposed.current) return tok;
+			setToken(tok);
+			props.onVerify && props.onVerify({
+				token: tok,
+				action: a
+			});
+			return tok;
+		}).catch((err) => {
+			if (!disposed.current) props.onError && props.onError({ error: err });
+			throw err;
+		});
+	}
+	(0, react.useEffect)(() => {
+		disposed.current = false;
+		loadRecaptchaV3(props.sitekey).then(() => {
+			if (disposed.current || !props.executeOnMount) return;
+			execute$1();
+		}).catch((err) => {
+			if (disposed.current) return;
+			props.onError && props.onError({ error: err });
+		});
+		return () => {
+			disposed.current = true;
+		};
+	}, []);
+	const _rozieExposeRef = (0, react.useRef)({ execute: execute$1 });
+	_rozieExposeRef.current = { execute: execute$1 };
+	(0, react.useImperativeHandle)(ref, () => ({ execute: (...args) => _rozieExposeRef.current.execute(...args) }), []);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		style: { display: "none" },
+		...attrs,
+		className: (0, _rozie_runtime_react.clsx)("rozie-recaptcha-v3", attrs.className),
+		"data-rozie-s-9148a0b0": ""
+	}) });
+});
+//#endregion
+exports.Captcha = Captcha;
+exports.RecaptchaV3 = RecaptchaV3;
+exports.default = Captcha;

package/dist/index.d.cts

@@ -0,0 +1,41 @@
+import * as React from "react";
+
+//#region src/Captcha.d.ts
+interface CaptchaProps {
+  provider?: string;
+  sitekey: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (next: string) => void;
+  theme?: string;
+  size?: string;
+  tabindex?: (number) | null;
+  options?: Record<string, unknown>;
+  onVerify?: (...args: unknown[]) => void;
+  onExpire?: (...args: unknown[]) => void;
+  onError?: (...args: unknown[]) => void;
+}
+interface CaptchaHandle {
+  reset: (...args: any[]) => any;
+  execute: (...args: any[]) => any;
+  getResponse: (...args: any[]) => any;
+}
+declare const Captcha: React.ForwardRefExoticComponent<CaptchaProps & React.RefAttributes<CaptchaHandle>>;
+//#endregion
+//#region src/RecaptchaV3.d.ts
+interface RecaptchaV3Props {
+  sitekey: string;
+  action?: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (next: string) => void;
+  executeOnMount?: boolean;
+  onError?: (...args: unknown[]) => void;
+  onVerify?: (...args: unknown[]) => void;
+}
+interface RecaptchaV3Handle {
+  execute: (...args: any[]) => any;
+}
+declare const RecaptchaV3: React.ForwardRefExoticComponent<RecaptchaV3Props & React.RefAttributes<RecaptchaV3Handle>>;
+//#endregion
+export { Captcha, Captcha as default, type CaptchaHandle, RecaptchaV3, type RecaptchaV3Handle };

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import * as _$react from "react";
+
+//#region src/Captcha.d.ts
+interface CaptchaProps {
+  provider?: string;
+  sitekey: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (token: string) => void;
+  theme?: string;
+  size?: string;
+  tabindex?: (number) | null;
+  options?: Record<string, any>;
+  onVerify?: (...args: any[]) => void;
+  onExpire?: (...args: any[]) => void;
+  onError?: (...args: any[]) => void;
+}
+interface CaptchaHandle {
+  reset: (...args: any[]) => any;
+  execute: (...args: any[]) => any;
+  getResponse: (...args: any[]) => any;
+}
+declare const Captcha: _$react.ForwardRefExoticComponent<CaptchaProps & _$react.RefAttributes<CaptchaHandle>>;
+//#endregion
+//#region src/RecaptchaV3.d.ts
+interface RecaptchaV3Props {
+  sitekey: string;
+  action?: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (token: string) => void;
+  executeOnMount?: boolean;
+  onError?: (...args: any[]) => void;
+  onVerify?: (...args: any[]) => void;
+}
+interface RecaptchaV3Handle {
+  execute: (...args: any[]) => any;
+}
+declare const RecaptchaV3: _$react.ForwardRefExoticComponent<RecaptchaV3Props & _$react.RefAttributes<RecaptchaV3Handle>>;
+//#endregion
+export { Captcha, Captcha as default, type CaptchaHandle, RecaptchaV3, type RecaptchaV3Handle };