@silverassist/recaptcha 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-02-06
+
+### Fixed
+
+- Fix race condition in lazy mode where `grecaptcha` was unavailable immediately after script load (#15)
+- Fix `act()` warnings in client tests by properly wrapping async callbacks
+- Fix TypeScript lint error for `tagName` property on `Node` type in tests
+
+### Changed
+
+- Add JSDoc module headers with `@module`, `@author`, `@license`, and `@version` tags to all source files
+- Document callback stability requirements (`useCallback`) in `onTokenGenerated` and `onError` props
+- Improve test coverage from 82% to 86% branch coverage with edge case tests
+- Suppress expected reCAPTCHA console logs during test execution
+- Update release prompt to include version sync for JSDoc headers
+
+### Dependencies
+
+- Bump `@types/node` from 25.0.10 to 25.2.0
+- Bump `@types/react` from 19.2.9 to 19.2.10
+- Bump `next` from 16.1.5 to 16.1.6
+
+## [0.2.0] - 2026-02-02
+
+### Added
+
+- **Lazy loading support** for better page performance
+  - New `lazy` prop to defer reCAPTCHA script loading until form is visible
+  - New `lazyRootMargin` prop to configure IntersectionObserver threshold (default: "200px")
+  - Reduces initial JS by ~320KB and improves TBT/TTI metrics
+- **Singleton script loading** prevents duplicate script loads across multiple forms
+- Comprehensive test coverage for lazy loading scenarios
+- Documentation for lazy loading with performance metrics
+
+### Fixed
+
+- Add IntersectionObserver feature detection with fallback to eager loading for older browsers/SSR environments
+- Add error handling tests for non-lazy Script component to ensure proper callback notification
+- Queued callbacks now properly receive error notifications on script load failure
+
 ## [0.1.0] - 2026-01-27
 
 ### Added

package/README.md

@@ -14,6 +14,8 @@ Google reCAPTCHA v3 integration for Next.js applications with Server Actions sup
 - ✅ **Auto Token Refresh**: Tokens refresh automatically before expiration
 - ✅ **Graceful Degradation**: Works in development without credentials
 - ✅ **Configurable Thresholds**: Custom score thresholds per form
+- ✅ **Lazy Loading**: Optional lazy loading for better performance
+- ✅ **Singleton Script Loading**: Prevents duplicate script loads across multiple forms
 
 ## Installation
 
@@ -92,6 +94,197 @@ export async function submitForm(formData: FormData) {
 }
 ```
 
+## ⚠️ Important: Custom FormData
+
+`RecaptchaWrapper` injects a **hidden input field** containing the reCAPTCHA token. If your form handler creates a custom `FormData` object, you must ensure the hidden token is included.
+
+### ❌ This will fail (token is missing):
+
+```tsx
+"use client";
+
+import { RecaptchaWrapper } from "@silverassist/recaptcha";
+import { submitForm } from "./actions"; // Your server action
+
+export function ContactForm() {
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    
+    // ❌ Creating empty FormData - hidden reCAPTCHA input is NOT included!
+    const formData = new FormData();
+    formData.set("email", "user@example.com");
+    formData.set("message", "Hello");
+    
+    await submitForm(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <RecaptchaWrapper action="contact_form" />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+### ✅ Recommended: Pass form element to capture all inputs
+
+```tsx
+"use client";
+
+import { RecaptchaWrapper } from "@silverassist/recaptcha";
+import { submitForm } from "./actions"; // Your server action
+
+export function ContactForm() {
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    
+    // ✅ Pass form element - captures ALL inputs including hidden reCAPTCHA token
+    const formData = new FormData(e.currentTarget);
+    
+    await submitForm(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <RecaptchaWrapper action="contact_form" />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+### ✅ Alternative: Start with form element, then modify
+
+```tsx
+"use client";
+
+import { RecaptchaWrapper } from "@silverassist/recaptcha";
+import { submitForm } from "./actions"; // Your server action
+
+export function ContactForm() {
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    
+    // ✅ Start with form element (includes hidden token)
+    const formData = new FormData(e.currentTarget);
+    
+    // Then add/override specific fields
+    formData.set("customField", "customValue");
+    formData.set("timestamp", Date.now().toString());
+    
+    await submitForm(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <RecaptchaWrapper action="contact_form" />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+## Performance Optimization: Lazy Loading
+
+The `lazy` prop enables lazy loading of the reCAPTCHA script, which defers loading until the form becomes visible in the viewport. This significantly improves initial page load performance.
+
+### Performance Benefits
+
+> **Note**: These metrics are approximate values measured on production websites using Google reCAPTCHA v3. Actual performance improvements will vary based on network conditions, device capabilities, and page complexity.
+
+| Metric | Without Lazy Loading | With Lazy Loading | Improvement |
+|--------|---------------------|-------------------|-------------|
+| **Initial JS** | 320KB+ | 0 KB (until visible) | -320KB |
+| **TBT (Total Blocking Time)** | ~470ms | ~0ms (deferred) | -470ms |
+| **TTI (Time to Interactive)** | +2-3s | Minimal impact | -2-3s |
+
+### Basic Lazy Loading
+
+Enable lazy loading by adding the `lazy` prop:
+
+```tsx
+"use client";
+
+import { RecaptchaWrapper } from "@silverassist/recaptcha";
+
+export function ContactForm() {
+  return (
+    <form action={submitForm}>
+      {/* Script loads only when form is near viewport */}
+      <RecaptchaWrapper action="contact_form" lazy />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+### Custom Root Margin
+
+Control when the script loads with the `lazyRootMargin` prop (default: `"200px"`):
+
+```tsx
+// Load script earlier (400px before entering viewport)
+<RecaptchaWrapper action="contact_form" lazy lazyRootMargin="400px" />
+
+// Load script later (load only when fully visible)
+<RecaptchaWrapper action="contact_form" lazy lazyRootMargin="0px" />
+
+// Load with negative margin (load only after scrolling past)
+<RecaptchaWrapper action="contact_form" lazy lazyRootMargin="-100px" />
+```
+
+### Best Practices
+
+#### 1. Use lazy loading for below-the-fold forms
+
+```tsx
+// Hero form (above the fold) - load immediately
+<RecaptchaWrapper action="hero_signup" />
+
+// Footer form (below the fold) - lazy load
+<RecaptchaWrapper action="footer_contact" lazy />
+```
+
+#### 2. Multiple forms on the same page
+
+The package automatically uses singleton script loading, so the script is only loaded once even with multiple forms:
+
+```tsx
+export function MultiFormPage() {
+  return (
+    <>
+      {/* First form triggers script load */}
+      <RecaptchaWrapper action="newsletter" lazy />
+      
+      {/* Second form reuses the same script */}
+      <RecaptchaWrapper action="contact" lazy />
+      
+      {/* Third form also reuses the script */}
+      <RecaptchaWrapper action="feedback" lazy />
+    </>
+  );
+}
+```
+
+#### 3. Adjust root margin based on form position
+
+```tsx
+// Form near top - smaller margin for faster load
+<RecaptchaWrapper action="signup" lazy lazyRootMargin="100px" />
+
+// Form far down page - larger margin to load in advance
+<RecaptchaWrapper action="newsletter" lazy lazyRootMargin="500px" />
+```
+
 ## API Reference
 
 ### RecaptchaWrapper
@@ -107,9 +300,25 @@ Client component that loads reCAPTCHA and generates tokens.
   refreshInterval={90000}    // Optional: token refresh interval in ms (default: 90000)
   onTokenGenerated={(token) => {}} // Optional: callback when token is generated
   onError={(error) => {}}    // Optional: callback on error
+  lazy={false}               // Optional: enable lazy loading (default: false)
+  lazyRootMargin="200px"     // Optional: IntersectionObserver rootMargin (default: "200px")
 />
 ```
 
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `action` | `string` | **Required** | Action name for reCAPTCHA analytics (e.g., "contact_form", "signup") |
+| `inputName` | `string` | `"recaptchaToken"` | Name attribute for the hidden input field |
+| `inputId` | `string` | `"recaptcha-token"` | ID attribute for the hidden input field |
+| `siteKey` | `string` | `process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY` | Override the site key from environment variable |
+| `refreshInterval` | `number` | `90000` | Token refresh interval in milliseconds (90 seconds) |
+| `onTokenGenerated` | `(token: string) => void` | `undefined` | Callback invoked when a new token is generated |
+| `onError` | `(error: Error) => void` | `undefined` | Callback invoked when an error occurs |
+| `lazy` | `boolean` | `false` | Enable lazy loading to defer script until form is visible |
+| `lazyRootMargin` | `string` | `"200px"` | IntersectionObserver rootMargin (used when `lazy` is true) |
+
 ### validateRecaptcha
 
 Server-side token validation function.

package/dist/client/index.d.mts

@@ -14,10 +14,34 @@ interface RecaptchaWrapperProps {
     siteKey?: string;
     /** Token refresh interval in ms (default: 90000 = 90 seconds) */
     refreshInterval?: number;
-    /** Callback when token is generated */
+    /**
+     * Callback when token is generated.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleToken = useCallback((token: string) => {
+     *   console.log('Token:', token);
+     * }, []);
+     * <RecaptchaWrapper action="form" onTokenGenerated={handleToken} />
+     * ```
+     */
     onTokenGenerated?: (token: string) => void;
-    /** Callback when an error occurs */
+    /**
+     * Callback when an error occurs.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleError = useCallback((error: Error) => {
+     *   console.error('reCAPTCHA error:', error);
+     * }, []);
+     * <RecaptchaWrapper action="form" onError={handleError} />
+     * ```
+     */
     onError?: (error: Error) => void;
+    /** Enable lazy loading (default: false for backward compatibility) */
+    lazy?: boolean;
+    /** IntersectionObserver rootMargin for lazy loading (default: "200px") */
+    lazyRootMargin?: string;
 }
 /**
  * Global window interface extension for reCAPTCHA
@@ -30,6 +54,15 @@ declare global {
                 action: string;
             }) => Promise<string>;
         };
+        /** Flag to track if reCAPTCHA script has loaded */
+        __recaptchaLoaded?: boolean;
+        /** Flag to track if reCAPTCHA script is currently loading */
+        __recaptchaLoading?: boolean;
+        /** Callbacks to execute when script finishes loading */
+        __recaptchaCallbacks?: Array<{
+            onLoad: () => void;
+            onError: (error: Error) => void;
+        }>;
     }
 }
 
@@ -42,6 +75,7 @@ declare global {
  * - Refreshes token periodically (tokens expire after 2 minutes)
  * - Stores token in hidden input field for form submission
  * - Graceful fallback when not configured
+ * - Lazy loading support to defer script loading until visible
  *
  * @example Basic usage
  * ```tsx
@@ -63,13 +97,32 @@ declare global {
  *
  * @example With callbacks
  * ```tsx
+ * // IMPORTANT: Memoize callbacks to prevent unnecessary re-renders
+ * const handleToken = useCallback((token: string) => {
+ *   console.log("Token:", token);
+ * }, []);
+ *
+ * const handleError = useCallback((error: Error) => {
+ *   console.error("Error:", error);
+ * }, []);
+ *
  * <RecaptchaWrapper
  *   action="payment"
- *   onTokenGenerated={(token) => console.log("Token:", token)}
- *   onError={(error) => console.error("Error:", error)}
+ *   onTokenGenerated={handleToken}
+ *   onError={handleError}
  * />
  * ```
+ *
+ * @example Lazy loading for better performance
+ * ```tsx
+ * <RecaptchaWrapper action="contact_form" lazy />
+ * ```
+ *
+ * @example Lazy loading with custom root margin
+ * ```tsx
+ * <RecaptchaWrapper action="contact_form" lazy lazyRootMargin="400px" />
+ * ```
  */
-declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
+declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, lazy, lazyRootMargin, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
 
 export { RecaptchaWrapper, RecaptchaWrapper as default };

package/dist/client/index.d.ts

@@ -14,10 +14,34 @@ interface RecaptchaWrapperProps {
     siteKey?: string;
     /** Token refresh interval in ms (default: 90000 = 90 seconds) */
     refreshInterval?: number;
-    /** Callback when token is generated */
+    /**
+     * Callback when token is generated.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleToken = useCallback((token: string) => {
+     *   console.log('Token:', token);
+     * }, []);
+     * <RecaptchaWrapper action="form" onTokenGenerated={handleToken} />
+     * ```
+     */
     onTokenGenerated?: (token: string) => void;
-    /** Callback when an error occurs */
+    /**
+     * Callback when an error occurs.
+     * @remarks Should be memoized with useCallback to prevent unnecessary re-renders.
+     * @example
+     * ```tsx
+     * const handleError = useCallback((error: Error) => {
+     *   console.error('reCAPTCHA error:', error);
+     * }, []);
+     * <RecaptchaWrapper action="form" onError={handleError} />
+     * ```
+     */
     onError?: (error: Error) => void;
+    /** Enable lazy loading (default: false for backward compatibility) */
+    lazy?: boolean;
+    /** IntersectionObserver rootMargin for lazy loading (default: "200px") */
+    lazyRootMargin?: string;
 }
 /**
  * Global window interface extension for reCAPTCHA
@@ -30,6 +54,15 @@ declare global {
                 action: string;
             }) => Promise<string>;
         };
+        /** Flag to track if reCAPTCHA script has loaded */
+        __recaptchaLoaded?: boolean;
+        /** Flag to track if reCAPTCHA script is currently loading */
+        __recaptchaLoading?: boolean;
+        /** Callbacks to execute when script finishes loading */
+        __recaptchaCallbacks?: Array<{
+            onLoad: () => void;
+            onError: (error: Error) => void;
+        }>;
     }
 }
 
@@ -42,6 +75,7 @@ declare global {
  * - Refreshes token periodically (tokens expire after 2 minutes)
  * - Stores token in hidden input field for form submission
  * - Graceful fallback when not configured
+ * - Lazy loading support to defer script loading until visible
  *
  * @example Basic usage
  * ```tsx
@@ -63,13 +97,32 @@ declare global {
  *
  * @example With callbacks
  * ```tsx
+ * // IMPORTANT: Memoize callbacks to prevent unnecessary re-renders
+ * const handleToken = useCallback((token: string) => {
+ *   console.log("Token:", token);
+ * }, []);
+ *
+ * const handleError = useCallback((error: Error) => {
+ *   console.error("Error:", error);
+ * }, []);
+ *
  * <RecaptchaWrapper
  *   action="payment"
- *   onTokenGenerated={(token) => console.log("Token:", token)}
- *   onError={(error) => console.error("Error:", error)}
+ *   onTokenGenerated={handleToken}
+ *   onError={handleError}
  * />
  * ```
+ *
+ * @example Lazy loading for better performance
+ * ```tsx
+ * <RecaptchaWrapper action="contact_form" lazy />
+ * ```
+ *
+ * @example Lazy loading with custom root margin
+ * ```tsx
+ * <RecaptchaWrapper action="contact_form" lazy lazyRootMargin="400px" />
+ * ```
  */
-declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
+declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, lazy, lazyRootMargin, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
 
 export { RecaptchaWrapper, RecaptchaWrapper as default };