@rozie-ui/captcha-react 0.1.3

package/src/RecaptchaV3.tsx

@@ -0,0 +1,109 @@
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { clsx, useControllableState } from '@rozie/runtime-react';
+// The v3 api.js loader (inject-once-per-sitekey singleton + ready-gate + token
+// execute) lives in a vendored internal module so its branchy logic is
+// unit-tested independent of any framework (see internal/loadRecaptchaV3.test.ts).
+// codegen copies src/internal/ into every leaf, so this import resolves ×6.
+import { loadRecaptchaV3, execute as v3Execute } from './internal/loadRecaptchaV3';
+
+// `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. Top-level — visible to both the mount body and the teardown. It also
+// guards a late execute() resolve that fires after the component unmounts.
+
+interface RecaptchaV3Props {
+  sitekey: string;
+  action?: string;
+  token?: string;
+  defaultToken?: string;
+  onTokenChange?: (token: string) => void;
+  executeOnMount?: boolean;
+  onError?: (...args: any[]) => void;
+  onVerify?: (...args: any[]) => void;
+}
+
+export interface RecaptchaV3Handle {
+  execute: (...args: any[]) => any;
+}
+
+const RecaptchaV3 = forwardRef<RecaptchaV3Handle, RecaptchaV3Props>(function RecaptchaV3(_props: RecaptchaV3Props, ref): JSX.Element {
+  const props: Omit<RecaptchaV3Props, 'action' | 'executeOnMount'> & { action: string; executeOnMount: boolean } = {
+    ..._props,
+    action: _props.action ?? 'submit',
+    executeOnMount: _props.executeOnMount ?? false,
+  };
+  const attrs: Record<string, unknown> = (() => {
+    const { sitekey, action, token, executeOnMount, defaultValue, onTokenChange, defaultToken, ...rest } = _props as RecaptchaV3Props & Record<string, unknown>;
+    void sitekey; void action; void token; void executeOnMount; void defaultValue; void onTokenChange; void defaultToken;
+    return rest;
+  })();
+  const disposed = useRef(false);
+  const [token, setToken] = useControllableState({
+    value: props.token,
+    defaultValue: props.defaultToken ?? '',
+    onValueChange: props.onTokenChange,
+  });
+
+  // Run a v3 challenge and return a fresh token. The optional `action` arg
+  // overrides the prop default for this one call. On success writes the two-way
+  // token + emits @verify; on failure emits @error. NB: the resolved 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). Use `tok` (mirrors Captcha.rozie's `response`).
+  //
+  // `action = null` (an explicit DEFAULT, not a bare `action`) makes the param
+  // OPTIONAL — required so the no-arg call in $onMount's executeOnMount path
+  // (`execute()`) typechecks. The type-neutralizer otherwise lowers a bare param
+  // to a REQUIRED `action: any`, which Vue's strict declaration emit (vue-tsc)
+  // rejects at the `execute()` call (TS2554) — the other five targets don't
+  // body-typecheck the emitted leaf, so the issue is Vue-only but real. The
+  // default is logic-neutral: the body already guards `action != null`.
+  function execute(action = null) {
+    const a = action != null ? action : props.action;
+    return loadRecaptchaV3(props.sitekey).then(() => v3Execute(props.sitekey, {
+      action: a
+    })).then((tok: any) => {
+      if (disposed.current) return tok;
+      setToken(tok);
+      props.onVerify && props.onVerify({
+        token: tok,
+        action: a
+      });
+      return tok;
+    }).catch((err: any) => {
+      if (!disposed.current) props.onError && props.onError({
+        error: err
+      });
+      throw err;
+    });
+  }
+
+  useEffect(() => {
+    disposed.current = false;
+    // Warm the script once for this sitekey. If opted in, run an initial execute.
+    loadRecaptchaV3(props.sitekey).then(() => {
+      if (disposed.current || !props.executeOnMount) return;
+      execute();
+    }).catch((err: any) => {
+      if (disposed.current) return;
+      props.onError && props.onError({
+        error: err
+      });
+    });
+    return () => {
+      disposed.current = true;
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const _rozieExposeRef = useRef({ execute });
+  _rozieExposeRef.current = { execute };
+  useImperativeHandle(ref, () => ({ execute: (...args: Parameters<typeof execute>): ReturnType<typeof execute> => _rozieExposeRef.current.execute(...args) }), []);
+
+  return (
+    <>
+    <div style={{ display: "none" }} {...attrs} className={clsx("rozie-recaptcha-v3", (attrs.className as string | undefined))} data-rozie-s-9148a0b0="" />
+    </>
+  );
+});
+export default RecaptchaV3;

package/src/index.ts

@@ -0,0 +1,9 @@
+export { default as Captcha } from './Captcha';
+export { default } from './Captcha';
+export { default as RecaptchaV3 } from './RecaptchaV3';
+
+/** The `$expose` imperative handle for Captcha received via `ref` — { reset, execute, getResponse }. */
+export type { CaptchaHandle } from './Captcha';
+
+/** The `$expose` imperative handle for RecaptchaV3 received via `ref` — { execute }. */
+export type { RecaptchaV3Handle } from './RecaptchaV3';

package/src/internal/loadCaptchaApi.ts

@@ -0,0 +1,174 @@
+// loadCaptchaApi.ts — provider api.js loader for the Captcha family.
+//
+// Extracted from Captcha.rozie so the one piece of real branchy logic (inject
+// once, poll until ready, cache per provider, timeout, error) is unit-testable
+// independent of any framework — the sortable-list `internal/useSortableJS`
+// pattern. codegen.mjs vendors this file (minus *.test.ts) into every leaf's
+// `src/internal/`, so the `./internal/loadCaptchaApi` import resolves verbatim
+// in all six compiled outputs.
+//
+// Framework-agnostic: touches only `document`, `globalThis`, and timers.
+
+/** The slice of a provider's global SDK this wrapper drives. */
+export interface CaptchaApi {
+  render: (el: Element, cfg: Record<string, unknown>) => unknown;
+  reset?: (id: unknown) => void;
+  execute?: (id: unknown) => void;
+  getResponse?: (id: unknown) => string;
+  remove?: (id: unknown) => void;
+}
+
+export interface ProviderConfig {
+  /** The api.js URL (`?render=explicit` so we own the render call + widget id). */
+  src: string;
+  /** The global name the script installs (`grecaptcha` / `hcaptcha` / `turnstile` / `frcaptcha`). */
+  global: string;
+  /**
+   * Optional bridge from the raw resolved global to the `CaptchaApi` shape.
+   *
+   * The original three providers (recaptcha/hcaptcha/turnstile) share the
+   * `render(el, cfg)`→id / `reset` / `execute` / `getResponse` surface, so they
+   * declare NO `adapt` and resolution is IDENTITY — the raw global IS the
+   * `CaptchaApi` unchanged (byte-for-byte the same behavior as before this hook
+   * existed). Friendly Captcha exposes a different SDK shape (`createWidget`
+   * returning an event-emitter handle), so it supplies an `adapt` that maps
+   * that surface onto `CaptchaApi`. When present, `adapt` is applied to the
+   * resolved global BEFORE the loader promise resolves / caches, so the cached
+   * value is always the adapted `CaptchaApi`, never the raw global.
+   */
+  adapt?: (global: unknown) => CaptchaApi;
+}
+
+/**
+ * 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: unknown): CaptchaApi => {
+  const fc = g as { createWidget: (opts: Record<string, unknown>) => FriendlyWidget };
+  return {
+    render(el: Element, cfg: Record<string, unknown>) {
+      const h = fc.createWidget({
+        element: el,
+        sitekey: cfg.sitekey,
+        theme: cfg.theme,
+        startMode: cfg.startMode,
+      });
+      h.addEventListener('frc:widget.complete', (e: FriendlyEvent) => {
+        const cb = cfg.callback as ((token: string) => void) | undefined;
+        if (typeof cb === 'function') cb(e.detail?.response ?? '');
+      });
+      h.addEventListener('frc:widget.expire', () => {
+        const cb = cfg['expired-callback'] as (() => void) | undefined;
+        if (typeof cb === 'function') cb();
+      });
+      h.addEventListener('frc:widget.error', () => {
+        const cb = cfg['error-callback'] as (() => void) | undefined;
+        if (typeof cb === 'function') cb();
+      });
+      return h;
+    },
+    reset: (id: unknown) => (id as FriendlyWidget).reset(),
+    execute: (id: unknown) => (id as FriendlyWidget).start(),
+    getResponse: (id: unknown) => (id as FriendlyWidget).getResponse(),
+    remove: (id: unknown) => (id as FriendlyWidget).destroy(),
+  };
+};
+
+/** The slice of an FC `createWidget` handle this bridge drives. */
+interface FriendlyWidget {
+  addEventListener: (type: string, cb: (e: FriendlyEvent) => void) => void;
+  reset: () => void;
+  start: () => void;
+  getResponse: () => string;
+  destroy: () => void;
+}
+interface FriendlyEvent {
+  detail?: { response?: string };
+}
+
+export const CAPTCHA_PROVIDERS: Record<string, ProviderConfig> = {
+  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 Captcha — a different SDK shape (`createWidget`), bridged onto
+  // CaptchaApi via `adapt`. CDN compat build pinned to the major (`@1`); NO
+  // `@friendlycaptcha/sdk` npm dependency (the family's zero-peer-dep design).
+  friendly: {
+    src: 'https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@1/site.compat.min.js',
+    global: 'frcaptcha',
+    adapt: adaptFriendly,
+  },
+};
+
+/** How long to poll for the provider global before giving up (ms). */
+export const LOAD_TIMEOUT_MS = 20000;
+
+type LoaderCache = Record<string, Promise<CaptchaApi>>;
+
+/**
+ * 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.
+ */
+export function loadCaptchaApi(
+  provider: string,
+  providers: Record<string, ProviderConfig> = CAPTCHA_PROVIDERS,
+): Promise<CaptchaApi> {
+  const cfg = providers[provider];
+  if (!cfg) return Promise.reject(new Error('Unknown captcha provider: ' + provider));
+
+  const root = globalThis as unknown as { __rozieCaptchaLoaders?: LoaderCache };
+  const cache = (root.__rozieCaptchaLoaders ||= {});
+  if (cache[provider]) return cache[provider];
+
+  const win = globalThis as unknown as Record<string, unknown>;
+  // A resolved global is "ready" once it exposes EITHER an explicit-render
+  // `render()` (recaptcha/hcaptcha/turnstile) OR FC's `createWidget()`. The
+  // `adapt` hook (when present) maps whichever shape arrived onto CaptchaApi.
+  const ready = (g: unknown): boolean => {
+    if (!g) return false;
+    const o = g as { render?: unknown; createWidget?: unknown };
+    return typeof o.render === 'function' || typeof o.createWidget === 'function';
+  };
+  // Resolve = the raw global, run through `adapt` when the provider supplies one.
+  const resolveApi = (g: unknown): CaptchaApi => (cfg.adapt ? cfg.adapt(g) : (g as CaptchaApi));
+
+  const p = new Promise<CaptchaApi>((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(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 > LOAD_TIMEOUT_MS) {
+        clearInterval(poll);
+        reject(new Error(provider + ' script load timeout'));
+      }
+    }, 50);
+  });
+
+  cache[provider] = p;
+  return p;
+}

package/src/internal/loadRecaptchaV3.ts

@@ -0,0 +1,117 @@
+// loadRecaptchaV3.ts — reCAPTCHA v3 api.js loader for the RecaptchaV3 family.
+//
+// reCAPTCHA v3 is scoreless and widget-less: there is NO render() and no DOM
+// element — the script URL carries the sitekey (`?render=SITEKEY`, distinct from
+// v2's `?render=explicit`), readiness is gated on `grecaptcha.ready(cb)`, and a
+// verification token comes from `grecaptcha.execute(sitekey, { action })`.
+//
+// Modeled on loadCaptchaApi.ts (same inject-once singleton + poll/timeout/error
+// discipline, same framework-agnostic constraint — touches only `document`,
+// `globalThis`, and timers), but with TWO v3-specific differences:
+//
+//   1. The singleton cache is keyed on the SITEKEY, not a provider name. v2 and
+//      v3 both install the same `grecaptcha` global, and v3 binds a sitekey at
+//      SCRIPT-LOAD time (it is in the URL). Keying on sitekey means two distinct
+//      sitekeys get two scripts + two cache entries, while the same sitekey
+//      twice shares one — and a v2 `<Captcha>` + a v3 `<RecaptchaV3>` on one page
+//      never collide on a single provider-name cache slot.
+//   2. Resolution waits for `grecaptcha.ready(cb)` (not just global presence) —
+//      v3's execute path is only safe once `ready` has fired.
+//
+// codegen.mjs vendors this file (minus *.test.ts) into every leaf's
+// `src/internal/`, so the `./internal/loadRecaptchaV3` import resolves verbatim
+// in all six compiled outputs.
+
+/** The v3 api.js base URL. The sitekey is appended (`render=SITEKEY`) per call. */
+export const RECAPTCHA_V3_SRC = 'https://www.google.com/recaptcha/api.js?render=';
+
+/** How long to poll for `grecaptcha` before giving up (ms). */
+export const LOAD_TIMEOUT_MS = 20000;
+
+/** The slice of the v3 `grecaptcha` global this loader drives. */
+export interface RecaptchaV3Global {
+  ready: (cb: () => void) => void;
+  execute: (sitekey: string, opts: { action: string }) => Promise<string>;
+}
+
+type LoaderCache = Record<string, Promise<RecaptchaV3Global>>;
+
+const getGrecaptcha = (): RecaptchaV3Global | undefined =>
+  (globalThis as unknown as { grecaptcha?: RecaptchaV3Global }).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).
+ */
+export function loadRecaptchaV3(sitekey: string, srcBase: string = RECAPTCHA_V3_SRC): Promise<RecaptchaV3Global> {
+  const root = globalThis as unknown as { __rozieRecaptchaV3Loaders?: LoaderCache };
+  const cache = (root.__rozieRecaptchaV3Loaders ||= {});
+  if (cache[sitekey]) return cache[sitekey];
+
+  const p = new Promise<RecaptchaV3Global>((resolve, reject) => {
+    let settled = false;
+    const ready = (g: RecaptchaV3Global) => {
+      // Gate on grecaptcha.ready() — v3 execute is only safe afterward.
+      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(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 > LOAD_TIMEOUT_MS) {
+        clearInterval(poll);
+        if (settled) return;
+        settled = true;
+        reject(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).
+ */
+export function execute(sitekey: string, opts: { action: string }): Promise<string> {
+  const g = getGrecaptcha();
+  if (!g || typeof g.execute !== 'function') {
+    return Promise.reject(new Error('reCAPTCHA v3 not loaded for sitekey: ' + sitekey));
+  }
+  return g.execute(sitekey, opts);
+}