@htmlbricks/hb-captcha-google-recaptcha-v2-invisible 0.71.35 → 0.71.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -23
- package/manifest.json +15 -13
- package/package.json +1 -1
- package/types/webcomponent.type.d.json +1 -7
- package/types/webcomponent.type.d.ts +0 -2
package/README.md
CHANGED
|
@@ -1,40 +1,81 @@
|
|
|
1
|
-
|
|
1
|
+
# `hb-captcha-google-recaptcha-v2-invisible`
|
|
2
2
|
|
|
3
|
-
**Category:** utilities
|
|
3
|
+
**Category:** utilities · **Tags:** utilities, security
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Summary
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
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**.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## What it does
|
|
10
10
|
|
|
11
|
-
`
|
|
11
|
+
- 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.
|
|
12
|
+
- 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.
|
|
13
|
+
- After a successful render, dispatches **`googleRecaptchaRendered`**, then from `onMount`’s load path calls **`grecaptcha.execute()`** once the widget is ready.
|
|
14
|
+
- Polls (starting after 1s, then 2s retries) until `window.grecaptcha` is available **and** `api_key` is set before rendering.
|
|
15
|
+
- On teardown, removes that script node and body div, clears the polling timer, and assigns `window.grecaptcha` to `undefined`.
|
|
12
16
|
|
|
13
|
-
|
|
17
|
+
## How it renders
|
|
14
18
|
|
|
15
|
-
|
|
19
|
+
- **Shadow root:** Forwards Bulma + component SCSS (`styles/bulma.scss`, `styles/webcomponent.scss`); there is **no** visible captcha UI inside the shadow tree.
|
|
20
|
+
- **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>`.
|
|
21
|
+
|
|
22
|
+
## Logic: site key, token, and `get`
|
|
23
|
+
|
|
24
|
+
- **Site key:** The `api_key` prop is passed to `grecaptcha.render(..., { sitekey: api_key, callback })`.
|
|
25
|
+
- **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()`).
|
|
26
|
+
- **`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”.
|
|
27
|
+
|
|
28
|
+
## Attributes / props (`Component`, snake_case)
|
|
29
|
+
|
|
30
|
+
| Name | Type (authoring) | Role |
|
|
16
31
|
| --- | --- | --- |
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
|
|
20
|
-
|
|
32
|
+
| `api_key` | `string` (optional) | reCAPTCHA **site key** passed to `grecaptcha.render` as `sitekey`. |
|
|
33
|
+
| `get` | optional (typed `any`) | Participates in the post-render `$effect` / `execCaptcha()` flow; see above (`get !== null`). |
|
|
34
|
+
|
|
35
|
+
HTML consumers should follow your platform’s rules for string attributes (e.g. booleans as `yes` / `no` where applicable).
|
|
36
|
+
|
|
37
|
+
## Events (`CustomEvent`)
|
|
38
|
+
|
|
39
|
+
| Event | `detail` (TypeScript) |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| `googleRecaptchaV2Response` | `{ response: string }` — verification token from the callback. |
|
|
42
|
+
| `googleRecaptchaRendered` | `{ render: true }` — fired once after `grecaptcha.render` completes in this component. |
|
|
43
|
+
|
|
44
|
+
## Styling
|
|
21
45
|
|
|
22
|
-
|
|
46
|
+
- Bulma theme tokens are forwarded onto **`:host`** even though the captcha UI is not in the shadow tree (`extra/docs.ts`).
|
|
47
|
+
- Documented CSS custom properties for catalog/style setup: **`--bulma-link`**, **`--bulma-text`** (colors; defaults follow the forwarded Bulma theme).
|
|
23
48
|
|
|
24
|
-
|
|
49
|
+
## Parts and slots
|
|
25
50
|
|
|
26
|
-
-
|
|
27
|
-
-
|
|
51
|
+
- **`::part`:** none (`cssParts` is empty).
|
|
52
|
+
- **Slots:** none (`htmlSlots` is empty).
|
|
28
53
|
|
|
29
|
-
|
|
54
|
+
## Typings
|
|
30
55
|
|
|
31
|
-
|
|
32
|
-
- Requires loading Google’s script; CSP and domain allowlisting apply outside the component.
|
|
33
|
-
- Shadow DOM wraps the widget; style invalid states through the exposed part.
|
|
34
|
-
- No i18n in `docs.ts`.
|
|
56
|
+
Authoring types live in `types/webcomponent.type.d.ts`:
|
|
35
57
|
|
|
36
|
-
|
|
58
|
+
- **`Component`:** `api_key?`, `get?`
|
|
59
|
+
- **`Events`:** `googleRecaptchaV2Response` → `{ response: string }`; `googleRecaptchaRendered` → `{ render: true }`
|
|
60
|
+
|
|
61
|
+
## Example
|
|
62
|
+
|
|
63
|
+
Google’s public **test** site key for v2 (always passes in test mode); replace with your production key.
|
|
37
64
|
|
|
38
65
|
```html
|
|
39
|
-
<hb-captcha-google-recaptcha-v2-invisible api_key="
|
|
66
|
+
<hb-captcha-google-recaptcha-v2-invisible api_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></hb-captcha-google-recaptcha-v2-invisible>
|
|
40
67
|
```
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
const el = document.querySelector("hb-captcha-google-recaptcha-v2-invisible");
|
|
71
|
+
|
|
72
|
+
el.addEventListener("googleRecaptchaRendered", (e) => {
|
|
73
|
+
console.log("rendered", e.detail); // { render: true }
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
el.addEventListener("googleRecaptchaV2Response", (e) => {
|
|
77
|
+
console.log("token", e.detail.response);
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Integrator note:** CSP, domain allowlisting, and Google’s key/domain configuration apply outside this component.
|
package/manifest.json
CHANGED
|
@@ -51,13 +51,7 @@
|
|
|
51
51
|
"api_key": {
|
|
52
52
|
"type": "string"
|
|
53
53
|
},
|
|
54
|
-
"get": {}
|
|
55
|
-
"id": {
|
|
56
|
-
"type": "string"
|
|
57
|
-
},
|
|
58
|
-
"style": {
|
|
59
|
-
"type": "string"
|
|
60
|
-
}
|
|
54
|
+
"get": {}
|
|
61
55
|
},
|
|
62
56
|
"type": "object"
|
|
63
57
|
}
|
|
@@ -84,13 +78,21 @@
|
|
|
84
78
|
}
|
|
85
79
|
},
|
|
86
80
|
"styleSetup": {
|
|
87
|
-
"vars": [
|
|
88
|
-
|
|
81
|
+
"vars": [
|
|
82
|
+
{
|
|
83
|
+
"name": "--bulma-link",
|
|
84
|
+
"valueType": "color",
|
|
85
|
+
"defaultValue": "(theme)",
|
|
86
|
+
"description": "Typical accent if you extend the host with custom markup; matches the global Bulma token stack on `:host`."
|
|
87
|
+
},
|
|
89
88
|
{
|
|
90
|
-
"name": "
|
|
91
|
-
"
|
|
89
|
+
"name": "--bulma-text",
|
|
90
|
+
"valueType": "color",
|
|
91
|
+
"defaultValue": "(theme)",
|
|
92
|
+
"description": "Default text token from the forwarded Bulma theme on `:host`."
|
|
92
93
|
}
|
|
93
|
-
]
|
|
94
|
+
],
|
|
95
|
+
"parts": []
|
|
94
96
|
},
|
|
95
97
|
"contributors": [],
|
|
96
98
|
"htmlSlots": [],
|
|
@@ -148,5 +150,5 @@
|
|
|
148
150
|
"size": {},
|
|
149
151
|
"iifePath": "main.iife.js",
|
|
150
152
|
"repoName": "@htmlbricks/hb-captcha-google-recaptcha-v2-invisible",
|
|
151
|
-
"version": "0.71.
|
|
153
|
+
"version": "0.71.37"
|
|
152
154
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@htmlbricks/hb-captcha-google-recaptcha-v2-invisible",
|
|
3
|
-
"version": "0.71.
|
|
3
|
+
"version": "0.71.37",
|
|
4
4
|
"contributors": [],
|
|
5
5
|
"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.",
|
|
6
6
|
"licenses": [
|