@rozie-ui/captcha-react 0.1.3

package/dist/index.mjs

@@ -0,0 +1,353 @@
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { clsx, useControllableState } from "@rozie/runtime-react";
+import { Fragment, jsx } from "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 = forwardRef(function Captcha(_props, ref) {
+	const __defaultOptions = 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 = useRef(false);
+	const api = useRef(null);
+	const widgetId = useRef(null);
+	const [token, setToken] = useControllableState({
+		value: props.token,
+		defaultValue: props.defaultToken ?? "",
+		onValueChange: props.onTokenChange
+	});
+	const widgetEl = useRef(null);
+	const { onError: _rozieProp_onError, onExpire: _rozieProp_onExpire, onVerify: _rozieProp_onVerify } = props;
+	const buildConfig = 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) : "";
+	}
+	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 = useRef({
+		reset,
+		execute,
+		getResponse
+	});
+	_rozieExposeRef.current = {
+		reset,
+		execute,
+		getResponse
+	};
+	useImperativeHandle(ref, () => ({
+		reset: (...args) => _rozieExposeRef.current.reset(...args),
+		execute: (...args) => _rozieExposeRef.current.execute(...args),
+		getResponse: (...args) => _rozieExposeRef.current.getResponse(...args)
+	}), []);
+	return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx("div", {
+		ref: widgetEl,
+		...attrs,
+		className: 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 = 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 = useRef(false);
+	const [token, setToken] = 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;
+		});
+	}
+	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 = useRef({ execute: execute$1 });
+	_rozieExposeRef.current = { execute: execute$1 };
+	useImperativeHandle(ref, () => ({ execute: (...args) => _rozieExposeRef.current.execute(...args) }), []);
+	return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx("div", {
+		style: { display: "none" },
+		...attrs,
+		className: clsx("rozie-recaptcha-v3", attrs.className),
+		"data-rozie-s-9148a0b0": ""
+	}) });
+});
+//#endregion
+export { Captcha, Captcha as default, RecaptchaV3 };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@rozie-ui/captcha-react",
+  "version": "0.1.3",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "Idiomatic React Captcha — one Rozie source compiled to React.",
+  "keywords": [
+    "rozie",
+    "rozie-ui",
+    "captcha",
+    "recaptcha",
+    "hcaptcha",
+    "turnstile",
+    "bot-protection",
+    "verification",
+    "spam",
+    "headless",
+    "component",
+    "react"
+  ],
+  "author": "One Learning Community (https://github.com/One-Learning-Community)",
+  "homepage": "https://github.com/One-Learning-Community/rozie.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/One-Learning-Community/rozie.js.git",
+    "directory": "packages/ui/captcha/packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/One-Learning-Community/rozie.js/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./source": "./src/Captcha.tsx"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@rozie/runtime-react": "0.1.1"
+  },
+  "peerDependencies": {
+    "react": "^18.2 || ^19",
+    "react-dom": "^18.2 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-dom": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Captcha.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import type { ForwardRefExoticComponent, RefAttributes } from 'react';
+import type * as React from 'react';
+
+export 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;
+}
+
+export interface CaptchaHandle {
+  reset: (...args: any[]) => any;
+  execute: (...args: any[]) => any;
+  getResponse: (...args: any[]) => any;
+}
+
+declare const Captcha: React.ForwardRefExoticComponent<CaptchaProps & React.RefAttributes<CaptchaHandle>>;
+export default Captcha;

package/src/Captcha.tsx

@@ -0,0 +1,141 @@
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { clsx, useControllableState } from '@rozie/runtime-react';
+// The provider api.js loader (inject-once singleton + poll/timeout/error) lives
+// in a vendored internal module so its branchy logic is unit-tested independent
+// of any framework (see internal/loadCaptchaApi.test.ts). codegen copies
+// src/internal/ into every leaf, so this relative import resolves verbatim ×6.
+import { loadCaptchaApi } from './internal/loadCaptchaApi';
+
+// Live widget handle. Top-level lets → React hoists to useRef (setup-once).
+// `disposed` MUST be top-level (not declared inside $onMount): the Solid emitter
+// extracts the teardown into a separate onCleanup() whose scope can't see a
+// mount-body local, so a `let disposed` inside $onMount is out of scope in the
+// teardown (TS2304). Top-level — like api/widgetId — is visible to both.
+
+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;
+}
+
+export interface CaptchaHandle {
+  reset: (...args: any[]) => any;
+  execute: (...args: any[]) => any;
+  getResponse: (...args: any[]) => any;
+}
+
+const Captcha = forwardRef<CaptchaHandle, CaptchaProps>(function Captcha(_props: CaptchaProps, ref): JSX.Element {
+  const __defaultOptions = useState(() => (() => ({}))())[0];
+  const props: Omit<CaptchaProps, 'provider' | 'theme' | 'size' | 'tabindex' | 'options'> & { provider: string; theme: string; size: string; tabindex: (number) | null; options: Record<string, any> } = {
+    ..._props,
+    provider: _props.provider ?? 'recaptcha',
+    theme: _props.theme ?? 'light',
+    size: _props.size ?? 'normal',
+    tabindex: _props.tabindex ?? null,
+    options: _props.options ?? __defaultOptions,
+  };
+  const attrs: Record<string, unknown> = (() => {
+    const { provider, sitekey, token, theme, size, tabindex, options, defaultValue, onTokenChange, defaultToken, ...rest } = _props as CaptchaProps & Record<string, unknown>;
+    void provider; void sitekey; void token; void theme; void size; void tabindex; void options; void defaultValue; void onTokenChange; void defaultToken;
+    return rest;
+  })();
+  const disposed = useRef(false);
+  const api = useRef<any>(null);
+  const widgetId = useRef<any>(null);
+  const [token, setToken] = useControllableState({
+    value: props.token,
+    defaultValue: props.defaultToken ?? '',
+    onValueChange: props.onTokenChange,
+  });
+  const widgetEl = useRef<HTMLDivElement | null>(null);
+
+  const { onError: _rozieProp_onError, onExpire: _rozieProp_onExpire, onVerify: _rozieProp_onVerify } = props;
+    const buildConfig = useCallback(() => ({
+    sitekey: props.sitekey,
+    theme: props.theme,
+    size: props.size,
+    ...(props.tabindex != null ? {
+      tabindex: props.tabindex
+    } : {}),
+    // NB: the param must NOT be named `token` — on Vue, $model.token lowers to a
+    // `defineModel('token')` ref named `token`, and a same-named param shadows it
+    // (`token.value = token` would write the param, not the model → v-model:token
+    // never populates). Vue-only footgun (React/Solid lower to a setToken call).
+    callback: (response: any) => {
+      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]);
+  // Imperative handle. Each guards on a live widget (null before render / after
+  // teardown). reset clears the two-way token to match the cleared widget.
+  function reset() {
+    if (widgetId.current != null && api.current && typeof api.current.reset === 'function') api.current.reset(widgetId.current);
+    setToken('');
+  }
+  // Invisible / programmatic challenge (size="invisible"). No-op until rendered.
+  // Invisible / programmatic challenge (size="invisible"). No-op until rendered.
+  function execute() {
+    if (widgetId.current != null && api.current && typeof api.current.execute === 'function') api.current.execute(widgetId.current);
+  }
+  // Read the current response token on demand (e.g. just before form submit).
+  // Read the current response token on demand (e.g. just before form submit).
+  function getResponse() {
+    return widgetId.current != null && api.current && typeof api.current.getResponse === 'function' ? api.current.getResponse(widgetId.current) : '';
+  }
+
+  useEffect(() => {
+    disposed.current = false;
+    loadCaptchaApi(props.provider).then((a: any) => {
+      if (disposed.current) return;
+      api.current = a;
+      widgetId.current = api.current.render(widgetEl.current!, buildConfig());
+    }).catch((err: any) => {
+      props.onError && props.onError({
+        provider: props.provider,
+        error: err
+      });
+    });
+    return () => {
+      disposed.current = true;
+      if (widgetId.current == null || !api.current) return;
+      // Turnstile fully removes a widget; reCAPTCHA/hCaptcha only reset.
+      if (typeof api.current.remove === 'function') api.current.remove(widgetId.current);else if (typeof api.current.reset === 'function') api.current.reset(widgetId.current);
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const _rozieExposeRef = useRef({ reset, execute, getResponse });
+  _rozieExposeRef.current = { reset, execute, getResponse };
+  useImperativeHandle(ref, () => ({ reset: (...args: Parameters<typeof reset>): ReturnType<typeof reset> => _rozieExposeRef.current.reset(...args), execute: (...args: Parameters<typeof execute>): ReturnType<typeof execute> => _rozieExposeRef.current.execute(...args), getResponse: (...args: Parameters<typeof getResponse>): ReturnType<typeof getResponse> => _rozieExposeRef.current.getResponse(...args) }), []);
+
+  return (
+    <>
+    <div ref={widgetEl} {...attrs} className={clsx("rozie-captcha", (attrs.className as string | undefined))} data-rozie-s-9c7749d4="" />
+    </>
+  );
+});
+export default Captcha;

package/src/RecaptchaV3.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import type { ForwardRefExoticComponent, RefAttributes } from 'react';
+import type * as React from 'react';
+
+export interface RecaptchaV3Props {
+  sitekey: string;
+  action?: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (next: string) => void;
+  executeOnMount?: boolean;
+  onError?: (...args: unknown[]) => void;
+  onVerify?: (...args: unknown[]) => void;
+}
+
+export interface RecaptchaV3Handle {
+  execute: (...args: any[]) => any;
+}
+
+declare const RecaptchaV3: React.ForwardRefExoticComponent<RecaptchaV3Props & React.RefAttributes<RecaptchaV3Handle>>;
+export default RecaptchaV3;