react-native-signature-canvas 4.7.4 → 5.0.1

package/WEBVIEW_PROPS.md

@@ -0,0 +1,166 @@
+# WebView Props Configuration
+
+The `react-native-signature-canvas` component now supports a `webviewProps` parameter that allows you to customize the underlying WebView behavior while maintaining the core signature functionality.
+
+## Usage
+
+```jsx
+import SignatureCanvas from 'react-native-signature-canvas';
+
+<SignatureCanvas
+  // ... other props
+  webviewProps={{
+    // Any WebView props can be passed here
+    cacheEnabled: false,
+    allowsFullscreenVideo: false,
+    decelerationRate: 'fast',
+    // ... more WebView props
+  }}
+/>
+```
+
+## Core vs Customizable Props
+
+### Core Props (Cannot be overridden)
+These props are essential for the signature functionality and cannot be overridden via `webviewProps`:
+
+- `ref` - Internal WebView reference
+- `source` - HTML content for signature pad
+- `onMessage` - Message handler for signature events
+- `onError` - Error handler (enhanced with retry logic)
+- `onLoadEnd` - Load completion handler
+- `onLoadStart` - Load start handler  
+- `onLoadProgress` - Load progress handler
+- `javaScriptEnabled` - Must be true for signature pad to work
+- `useWebKit` - Uses modern WebKit engine
+
+### Default Props (Can be overridden)
+These props have sensible defaults but can be customized via `webviewProps`:
+
+#### Performance Optimizations
+```jsx
+webviewProps={{
+  cacheEnabled: true, // Enable/disable WebView cache
+  allowsInlineMediaPlayback: false, // Disable media playback
+  mediaPlaybackRequiresUserAction: true, // Require user action for media
+  allowsBackForwardNavigationGestures: false, // Disable navigation gestures
+}}
+```
+
+#### Security Enhancements
+```jsx
+webviewProps={{
+  allowsLinkPreview: false, // Disable link previews
+  allowFileAccess: false, // Disable file access
+  allowFileAccessFromFileURLs: false, // Disable file URL access
+  allowUniversalAccessFromFileURLs: false, // Disable universal access
+  mixedContentMode: "never", // Block mixed content
+  originWhitelist: ['*'], // Allow all origins
+}}
+```
+
+#### UI/UX Customization
+```jsx
+webviewProps={{
+  bounces: false, // Disable bounce effect
+  scrollEnabled: false, // Disable scrolling (use scrollable prop instead)
+  decelerationRate: 'fast', // Scroll deceleration rate
+  showsHorizontalScrollIndicator: false, // Hide horizontal scroll
+  showsVerticalScrollIndicator: false, // Hide vertical scroll
+}}
+```
+
+#### Android-Specific
+```jsx
+webviewProps={{
+  androidLayerType: "hardware", // Use hardware acceleration
+  androidHardwareAccelerationDisabled: false, // Enable hardware acceleration
+}}
+```
+
+## Common Use Cases
+
+### High Performance Mode
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: true,
+    androidLayerType: "hardware",
+    androidHardwareAccelerationDisabled: false,
+  }}
+/>
+```
+
+### Low Memory Mode
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: false,
+    androidLayerType: "software",
+    androidHardwareAccelerationDisabled: true,
+  }}
+/>
+```
+
+### Enhanced Security
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    allowFileAccess: false,
+    allowFileAccessFromFileURLs: false,
+    allowUniversalAccessFromFileURLs: false,
+    mixedContentMode: "never",
+    originWhitelist: [], // Block all external origins
+  }}
+/>
+```
+
+### Custom Scrolling Behavior
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    decelerationRate: 'normal',
+    alwaysBounceVertical: false,
+    alwaysBounceHorizontal: false,
+    directionalLockEnabled: true,
+  }}
+/>
+```
+
+## Important Notes
+
+1. **Core Functionality**: The `webviewProps` cannot override core functionality props. These are protected to ensure the signature canvas works correctly.
+
+2. **Prop Priority**: User-provided `webviewProps` take precedence over default props but not core props.
+
+3. **TypeScript Support**: The `webviewProps` parameter is fully typed with `Partial<WebViewProps>` from `react-native-webview`.
+
+4. **Performance Impact**: Some WebView props can significantly impact performance. Test thoroughly when customizing performance-related settings.
+
+5. **Platform Differences**: Some props may behave differently on iOS vs Android. Refer to the `react-native-webview` documentation for platform-specific behavior.
+
+## Migration from Previous Versions
+
+If you were previously using individual WebView-related props, you can now consolidate them under `webviewProps`:
+
+### Before
+```jsx
+<SignatureCanvas
+  androidLayerType="hardware"
+  androidHardwareAccelerationDisabled={false}
+  // other props...
+/>
+```
+
+### After  
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    androidLayerType: "hardware",
+    androidHardwareAccelerationDisabled: false,
+  }}
+  // other props...
+/>
+```
+
+Note: The old individual props are still supported for backward compatibility.

package/h5/js/app.js

@@ -1,28 +1,54 @@
 export default `
+    // Enhanced error handling and validation
     var wrapper = document.getElementById("signature-pad"),
-        clearButton = wrapper.querySelector("[data-action=clear]"),
-        saveButton = wrapper.querySelector("[data-action=save]"),
-        canvas = wrapper.querySelector("canvas"),
+        clearButton = wrapper && wrapper.querySelector("[data-action=clear]"),
+        saveButton = wrapper && wrapper.querySelector("[data-action=save]"),
+        canvas = wrapper && wrapper.querySelector("canvas"),
         signaturePad;
+        
+    if (!wrapper || !canvas) {
+        console.error('Required DOM elements not found');
+    }
+    
+    // Enhanced canvas resize with debouncing
+    function debounce(func, wait) {
+        var timeout;
+        return function executedFunction() {
+            var later = function() {
+                clearTimeout(timeout);
+                func.apply(this, arguments);
+            };
+            clearTimeout(timeout);
+            timeout = setTimeout(later, wait);
+        };
+    }
     
-    // Adjust canvas coordinate space taking into account pixel ratio,
-    // to make it look crisp on mobile devices.
-    // This also causes canvas to be cleared.
     function resizeCanvas() {
-        // When zoomed out to less than 100%, for some very strange reason,
-        // some browsers report devicePixelRatio as less than 1
-        // and only part of the canvas is cleared then.
-        var context = canvas.getContext("2d"); //context.getImageData(0,0,canvas.width,canvas.height)
-        var imgData = signaturePad ? signaturePad.toData() : null;
-        var ratio =  Math.max(window.devicePixelRatio || 1, 1);
-        canvas.width = canvas.offsetWidth * ratio;
-        canvas.height = canvas.offsetHeight * ratio;
-        context.scale(ratio, ratio);
-        // context.putImageData(imgData,0,0);
-        imgData && signaturePad.fromData(imgData);
+        if (!canvas || !canvas.getContext) {
+            console.warn('Canvas not available for resize');
+            return;
+        }
+        
+        try {
+            var context = canvas.getContext("2d");
+            var imgData = signaturePad ? signaturePad.toData() : null;
+            var ratio = Math.max(window.devicePixelRatio || 1, 1);
+            
+            canvas.width = canvas.offsetWidth * ratio;
+            canvas.height = canvas.offsetHeight * ratio;
+            context.scale(ratio, ratio);
+            
+            if (imgData && signaturePad) {
+                signaturePad.fromData(imgData);
+            }
+        } catch (error) {
+            console.error('Error resizing canvas:', error);
+        }
     }
     
-    window.onresize = resizeCanvas;
+    // Use debounced resize handler
+    var debouncedResize = debounce(resizeCanvas, 100);
+    window.addEventListener('resize', debouncedResize);
     resizeCanvas();
     
     signaturePad = new SignaturePad(canvas, {
@@ -52,14 +78,30 @@ export default `
       }
 
     function changePenColor(color) {
+        if (!signaturePad) {
+            console.warn('SignaturePad not initialized');
+            return;
+        }
+        
         signaturePad.penColor = color;
-        window.ReactNativeWebView.postMessage("CHANGE_PEN");
+        window.ReactNativeWebView && window.ReactNativeWebView.postMessage("CHANGE_PEN");
     }
 
     function changePenSize(minW, maxW) {
-      signaturePad.minWidth = minW;
-      signaturePad.maxWidth = maxW;
-      window.ReactNativeWebView.postMessage("CHANGE_PEN_SIZE");
+        if (!signaturePad) {
+            console.warn('SignaturePad not initialized');
+            return;
+        }
+        
+        // Validate numeric values
+        if (typeof minW !== 'number' || typeof maxW !== 'number' || minW < 0 || maxW < minW) {
+            console.warn('Invalid pen size values:', minW, maxW);
+            return;
+        }
+        
+        signaturePad.minWidth = minW;
+        signaturePad.maxWidth = maxW;
+        window.ReactNativeWebView && window.ReactNativeWebView.postMessage("CHANGE_PEN_SIZE");
     }
     
     function getData () {
@@ -67,6 +109,11 @@ export default `
         window.ReactNativeWebView.postMessage(JSON.stringify(data));
     }
 
+    function fromData (pointGroups) {
+        signaturePad.fromData(pointGroups);
+        window.ReactNativeWebView.postMessage(JSON.stringify(pointGroups));
+    }
+
     function draw() {
       signaturePad.draw();
       window.ReactNativeWebView.postMessage("DRAW");
@@ -87,8 +134,8 @@ export default `
 
         //-----------------------------------------//
         function removeImageBlanks(imageObject) {
-            imgWidth = imageObject.width;
-            imgHeight = imageObject.height;
+            var imgWidth = imageObject.width;
+            var imgHeight = imageObject.height;
             var canvas = document.createElement('canvas');
             canvas.setAttribute("width", imgWidth);
             canvas.setAttribute("height", imgHeight);
@@ -97,7 +144,10 @@ export default `
 
             var imageData = context.getImageData(0, 0, imgWidth, imgHeight),
                 data = imageData.data,
-                getRBG = function(x, y) {
+                getRGB = function(x, y) {
+                    if (x < 0 || x >= imgWidth || y < 0 || y >= imgHeight) {
+                        return { red: 255, green: 255, blue: 255, opacity: 255 };
+                    }
                     var offset = imgWidth * y + x;
                     return {
                         red:     data[offset * 4],
@@ -118,7 +168,7 @@ export default `
 
                     // loop through each column
                     for(var x = 0; x < imgWidth; x++) {
-                        var rgb = getRBG(x, y);
+                        var rgb = getRGB(x, y);
                         if (!isWhite(rgb)) {
                             if (fromTop) {
                                 return y;
@@ -138,7 +188,7 @@ export default `
 
                     // loop through each row
                     for(var y = 0; y < imgHeight; y++) {
-                        var rgb = getRBG(x, y);
+                        var rgb = getRGB(x, y);
                         if (!isWhite(rgb)) {
                             if (fromLeft) {
                                 return x;
@@ -169,13 +219,31 @@ export default `
         }
     }
 
-    function readSignature()  {
-        if (signaturePad.isEmpty()) {
-            window.ReactNativeWebView.postMessage("EMPTY");
-        } else {
-            var url = signaturePad.toDataURL('<%imageType%>');
-            trimWhitespace? cropWhitespace(url): window.ReactNativeWebView.postMessage(url);
-            if (autoClear) signaturePad.clear();
+    function readSignature() {
+        if (!signaturePad) {
+            console.warn('SignaturePad not initialized');
+            return;
+        }
+        
+        try {
+            if (signaturePad.isEmpty()) {
+                window.ReactNativeWebView && window.ReactNativeWebView.postMessage("EMPTY");
+            } else {
+                var imageType = '<%imageType%>' || 'image/png';
+                var url = signaturePad.toDataURL(imageType);
+                
+                if (trimWhitespace === true) {
+                    cropWhitespace(url);
+                } else {
+                    window.ReactNativeWebView && window.ReactNativeWebView.postMessage(url);
+                }
+                
+                if (autoClear === true && signaturePad) {
+                    signaturePad.clear();
+                }
+            }
+        } catch (error) {
+            console.error('Error reading signature:', error);
         }
     }
 
@@ -187,10 +255,22 @@ export default `
 
     if (dataURL) signaturePad.fromDataURL(dataURL);
 
-    clearButton.addEventListener("click", clearSignature );
+    if (clearButton) {
+        clearButton.addEventListener("click", clearSignature);
+    }
 
-    saveButton.addEventListener("click", () => {    
-      readSignature();
-      getData();    
-    });
+    // Prevent race conditions by sequencing operations
+    if (saveButton) {
+        saveButton.addEventListener("click", function() {
+            try {
+                readSignature();
+                // Small delay to prevent race condition
+                setTimeout(function() {
+                    getData();
+                }, 10);
+            } catch (error) {
+                console.error('Error in save button click:', error);
+            }
+        });
+    }
 `;

package/index.d.ts

@@ -1,16 +1,24 @@
 declare module "react-native-signature-canvas" {
   import React from "react";
   import { StyleProp, ViewStyle } from "react-native";
+  import { WebViewProps } from "react-native-webview";
+
+  // Enhanced type definitions with better error handling
 
   type ImageType = "image/png" | "image/jpeg" | "image/svg+xml";
 
-  type DataURL = "Base64" | string;
+  type DataURL = string; // Simplified - should be base64 data URL
 
   type ForwardRef<T, P> = React.ForwardRefExoticComponent<
     React.PropsWithoutRef<P> & React.RefAttributes<T>
   >;
 
-  type SignatureViewProps = {
+  // Enhanced callback types
+  type SignatureCallback = (signature: string) => void;
+  type EmptyCallback = () => void;
+  type ErrorCallback = (error: Error) => void;
+
+  export type SignatureViewProps = {
     androidHardwareAccelerationDisabled?: boolean;
     autoClear?: boolean;
     backgroundColor?: string;
@@ -27,21 +35,23 @@ declare module "react-native-signature-canvas" {
     minWidth?: number;
     maxWidth?: number;
     minDistance?: number;
+    onError?: ErrorCallback; // Added missing prop
     nestedScrollEnabled?: boolean;
     showsVerticalScrollIndicator?: boolean;
-    onOK?: (signature: string) => void;
-    onEmpty?: () => void;
-    onClear?: () => void;
-    onUndo?: () => void;
-    onRedo?: () => void;
-    onDraw?: () => void;
-    onErase?: () => void;
-    onGetData?: (data: any) => void;
-    onChangePenColor?: () => void;
-    onChangePenSize?: () => void;
-    onBegin?: () => void;
-    onEnd?: () => void;
-    onLoadEnd?: () => void;
+    onOK?: SignatureCallback;
+    onEmpty?: EmptyCallback;
+    onClear?: EmptyCallback;
+    onUndo?: EmptyCallback;
+    onRedo?: EmptyCallback;
+    onDraw?: EmptyCallback;
+    onErase?: EmptyCallback;
+    onGetData?: (data: string) => void; // Should be JSON string
+    onChangePenColor?: EmptyCallback;
+    onChangePenSize?: EmptyCallback;
+    onBegin?: EmptyCallback;
+    onEnd?: EmptyCallback;
+    onLoadEnd?: EmptyCallback;
+    onError?: ErrorCallback; // Added missing error callback
     overlayHeight?: number;
     overlayWidth?: number;
     overlaySrc?: string;
@@ -53,21 +63,32 @@ declare module "react-native-signature-canvas" {
     webStyle?: string;
     webviewContainerStyle?: StyleProp<ViewStyle>;
     androidLayerType?: "none" | "software" | "hardware";
+    webviewProps?: Partial<WebViewProps>;
   };
 
   export type SignatureViewRef = {
     changePenColor: (color: string) => void;
     changePenSize: (minW: number, maxW: number) => void;
     clearSignature: () => void;
-    cropWhitespace: (url: string) => void;
     draw: () => void;
     erase: () => void;
     getData: () => void;
     readSignature: () => void;
     undo: () => void;
     redo: () => void;
+    fromData: (pointGroups, suppressClear = false) => void;
+    // Removed cropWhitespace as it's not exposed in the component
   };
 
-  const SignatureView: ForwardRef<SignatureViewRef, SignatureViewProps>;
+  // Enhanced component interface with better type safety
+  interface SignatureCanvasComponent
+    extends ForwardRef<SignatureViewRef, SignatureViewProps> {
+    displayName?: string;
+  }
+
+  const SignatureView: SignatureCanvasComponent;
   export default SignatureView;
+
+  // Export additional types for external use
+  export { SignatureViewProps, SignatureViewRef, ImageType, DataURL };
 }