@htmlbricks/hb-captcha-google-recaptcha-v2-invisible 0.71.35 → 0.71.36

package/README.md

@@ -1,40 +1,83 @@
-## `hb-captcha-google-recaptcha-v2-invisible` — captcha-google-recaptcha-v2-invisible
+# `hb-captcha-google-recaptcha-v2-invisible`
 
-**Category:** utilities | **Tags:** utilities, security
+**Category:** utilities · **Tags:** utilities, security
 
-### What it does
+## Summary
 
-Loads the Google reCAPTCHA v2 invisible SDK, renders the widget with your `api_key`, and exposes `grecaptcha.execute()` / reset when the `get` attribute changes after render. Dispatches `googleRecaptchaRendered` once mounted and `googleRecaptchaV2Response` with the token from the verification callback.
+Custom element that loads Google’s reCAPTCHA v2 **explicit** API, mounts an **invisible** widget in the document **light DOM**, runs execution when the SDK is ready, and surfaces the verification token and render lifecycle through **custom events**.
 
-### Custom element
+## What it does
 
-`hb-captcha-google-recaptcha-v2-invisible`
+- Injects `https://www.google.com/recaptcha/api.js?render=explicit` (async/defer) into `document.head` with a stable script id (`recaptchav2-sdk`), if not already present.
+- Ensures a host div exists on `document.body` with id `recaptchav2-element`, `data-size="invisible"`, then calls `grecaptcha.render()` with your site key (`api_key`) and a callback that dispatches the response event.
+- After a successful render, dispatches **`googleRecaptchaRendered`**, then from `onMount`’s load path calls **`grecaptcha.execute()`** once the widget is ready.
+- Polls (starting after 1s, then 2s retries) until `window.grecaptcha` is available **and** `api_key` is set before rendering.
+- On teardown, removes that script node and body div, clears the polling timer, and assigns `window.grecaptcha` to `undefined`.
 
-### Attributes / props (snake_case)
+## How it renders
 
-| Property | Type | Notes |
+- **Shadow root:** Forwards Bulma + component SCSS (`styles/bulma.scss`, `styles/webcomponent.scss`); there is **no** visible captcha UI inside the shadow tree.
+- **Light DOM / Google widget:** The actual reCAPTCHA widget is attached via the **`recaptchav2-element`** div appended to **`document.body`** (not inside the custom element). Integrators should assume global script injection and a body-level placeholder, not a child of `<hb-captcha-google-recaptcha-v2-invisible>`.
+
+## Logic: site key, token, and `get`
+
+- **Site key:** The `api_key` prop is passed to `grecaptcha.render(..., { sitekey: api_key, callback })`.
+- **Token:** When Google invokes the callback, the component dispatches **`googleRecaptchaV2Response`** with **`detail.response`** (string). The implementation also toggles internal state so a later programmatic run can **`reset()`** then **`execute()`** if a response was already produced (`execCaptcha()`).
+- **`get`:** An `$effect` runs when reactive dependencies change (including `get`). After the widget has rendered and an internal “ready” latch is set, if **`get !== null`** it calls `execCaptcha()` again (execute, or reset+execute if a response was already received). So **`null`** suppresses that path; **`undefined`** and other non-`null` values still satisfy `get !== null` once the latch is set—align testing with that condition, not only “attribute changed”.
+
+## Attributes / props (`Component`, snake_case)
+
+| Name | Type (authoring) | Role |
 | --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `api_key` | string (optional) | Google reCAPTCHA site key. |
-| `get` | any (optional) | Trigger prop: changing after render drives execute/reset (see component behavior). |
+| `api_key` | `string` (optional) | reCAPTCHA **site key** passed to `grecaptcha.render` as `sitekey`. |
+| `get` | optional (typed `any`) | Participates in the post-render `$effect` / `execCaptcha()` flow; see above (`get !== null`). |
+| `id` | `string` (optional) | Declared on `Component`; standard host id if your toolchain maps it. |
+| `style` | `string` (optional) | Declared on `Component`; standard host inline style if your toolchain maps it. |
+
+HTML consumers should follow your platform’s rules for string attributes (e.g. booleans as `yes` / `no` where applicable).
+
+## Events (`CustomEvent`)
+
+| Event | `detail` (TypeScript) |
+| --- | --- |
+| `googleRecaptchaV2Response` | `{ response: string }` — verification token from the callback. |
+| `googleRecaptchaRendered` | `{ render: true }` — fired once after `grecaptcha.render` completes in this component. |
+
+## Styling
 
-**Bootstrap theme vars** in metadata. **CSS part:** `invalid-feedback`. No slots.
+- Bulma theme tokens are forwarded onto **`:host`** even though the captcha UI is not in the shadow tree (`extra/docs.ts`).
+- Documented CSS custom properties for catalog/style setup: **`--bulma-link`**, **`--bulma-text`** (colors; defaults follow the forwarded Bulma theme).
 
-### Events (`CustomEvent` names)
+## Parts and slots
 
-- **`googleRecaptchaV2Response`** — `{ response: string }` — Verification token from Google.
-- **`googleRecaptchaRendered`** — `{ render: true }` — Widget finished rendering.
+- **`::part`:** none (`cssParts` is empty).
+- **Slots:** none (`htmlSlots` is empty).
 
-### Usage notes
+## Typings
 
-- Uses Bootstrap form-feedback styling via the `invalid-feedback` part.
-- Requires loading Google’s script; CSP and domain allowlisting apply outside the component.
-- Shadow DOM wraps the widget; style invalid states through the exposed part.
-- No i18n in `docs.ts`.
+Authoring types live in `types/webcomponent.type.d.ts`:
 
-### Minimal HTML example
+- **`Component`:** `id?`, `style?`, `api_key?`, `get?`
+- **`Events`:** `googleRecaptchaV2Response` → `{ response: string }`; `googleRecaptchaRendered` → `{ render: true }`
+
+## Example
+
+Google’s public **test** site key for v2 (always passes in test mode); replace with your production key.
 
 ```html
-<hb-captcha-google-recaptcha-v2-invisible api_key="YOUR_SITE_KEY"></hb-captcha-google-recaptcha-v2-invisible>
+<hb-captcha-google-recaptcha-v2-invisible api_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></hb-captcha-google-recaptcha-v2-invisible>
 ```
+
+```js
+const el = document.querySelector("hb-captcha-google-recaptcha-v2-invisible");
+
+el.addEventListener("googleRecaptchaRendered", (e) => {
+  console.log("rendered", e.detail); // { render: true }
+});
+
+el.addEventListener("googleRecaptchaV2Response", (e) => {
+  console.log("token", e.detail.response);
+});
+```
+
+**Integrator note:** CSP, domain allowlisting, and Google’s key/domain configuration apply outside this component.

package/manifest.json

@@ -84,13 +84,21 @@
     }
   },
   "styleSetup": {
-    "vars": [],
-    "parts": [
+    "vars": [
       {
-        "name": "invalid-feedback",
-        "description": ""
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Typical accent if you extend the host with custom markup; matches the global Bulma token stack on `:host`."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Default text token from the forwarded Bulma theme on `:host`."
       }
-    ]
+    ],
+    "parts": []
   },
   "contributors": [],
   "htmlSlots": [],
@@ -148,5 +156,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-captcha-google-recaptcha-v2-invisible",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-captcha-google-recaptcha-v2-invisible",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Loads the Google reCAPTCHA v2 invisible SDK, renders the widget with your `api_key`, and exposes `grecaptcha.execute()` / reset when the `get` attribute changes after render. Dispatches `googleRecaptchaRendered` once mounted and `googleRecaptchaV2Response` with the token from the verification callback.",
   "licenses": [