react-native-signature-canvas 4.7.4 → 5.0.0

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+# [5.0.0](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.5.1...v5.0.0) (2025-06-28)
+
+
+### Bug Fixes
+
+* add originWhitelist prop ([068c646](https://github.com/YanYuanFE/react-native-signature-canvas/commit/068c6467d1e9910c4911e727b2144e065a9a7322))
+* backgorund color to transparent and loader color to transparent ([3001d4e](https://github.com/YanYuanFE/react-native-signature-canvas/commit/3001d4edfdcf1806e2f16a518d25f1690b80557e))
+* fix canvas not display for android api 28 ([835669b](https://github.com/YanYuanFE/react-native-signature-canvas/commit/835669bb65ab5c88c43830b7a783eed105f3910d))
+
+
+### Features
+
+* add onLoadEnd prop ([49a8664](https://github.com/YanYuanFE/react-native-signature-canvas/commit/49a866408b6356ce9e71b1c794993a3f2fe85337))
+* add showsVerticalScrollIndicator prop ([a4d64c5](https://github.com/YanYuanFE/react-native-signature-canvas/commit/a4d64c5754a9da4ecb9d531a1585a38994d18d6d))
+* export SignatureViewProps ([8f0c321](https://github.com/YanYuanFE/react-native-signature-canvas/commit/8f0c3211b20782cd8f35a43083f39d5ea351f932))
+
+
+
+## [4.5.1](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.3.0...v4.5.1) (2023-05-04)
+
+
+### Bug Fixes
+
+* **android:** sigsegv crash on android ([49644b8](https://github.com/YanYuanFE/react-native-signature-canvas/commit/49644b802a7cb80443292972b1fbd3d4dbdfd9c4))
+* fix bgSrc props ([bef3ab2](https://github.com/YanYuanFE/react-native-signature-canvas/commit/bef3ab27ebb990a94dd74517ab67754d557307ae))
+* fix webview version ([1b55f45](https://github.com/YanYuanFE/react-native-signature-canvas/commit/1b55f45e27560cd8b0bdf62504a7d27b412687c2))
+
+
+### Features
+
+* update rn latest example ([f9a568f](https://github.com/YanYuanFE/react-native-signature-canvas/commit/f9a568f68c966690ee2ec1b300b2e2fb6f18ee56))
+
+
+
+# [4.3.0](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.2.1...v4.3.0) (2021-08-11)
+
+
+
+## [4.2.1](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.2.0...v4.2.1) (2021-08-04)
+
+
+### Bug Fixes
+
+* ts imageType ([d50d227](https://github.com/YanYuanFE/react-native-signature-canvas/commit/d50d22747278f860152ff1c8a87be6e335236724))
+
+
+
+# [4.2.0](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.1.0...v4.2.0) (2021-07-24)
+
+
+
 # [4.1.0](https://github.com/YanYuanFE/react-native-signature-canvas/compare/v4.0.0...v4.1.0) (2021-07-14)
 
 

package/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `react-native-signature-canvas`, a React Native library for capturing signatures and drawing on a canvas. The library provides a WebView-based signature pad component with smooth drawing capabilities across iOS, Android, and Expo.
+
+## Core Architecture
+
+The library uses a hybrid architecture combining React Native and web technologies:
+
+- **Main Component** (`index.js`): The React Native component that wraps a WebView
+- **WebView Content** (`h5/`): HTML, CSS, and JavaScript that runs inside the WebView
+  - `html.js`: HTML template with placeholder variables for configuration
+  - `js/signature_pad.js`: Core signature pad functionality 
+  - `js/app.js`: Application logic for handling signature interactions
+  - `css/signature-pad.css`: Styling for the signature pad interface
+- **TypeScript Definitions** (`index.d.ts`): Type definitions for props and ref methods
+
+### Key Technical Details
+
+1. **Communication**: React Native communicates with the WebView through:
+   - `injectedJavaScript`: JavaScript code injected into the WebView
+   - `onMessage`: Messages sent from WebView to React Native
+   - Template variables in HTML (e.g., `<%penColor%>`, `<%bgSrc%>`)
+
+2. **Signature Export**: Signatures are captured as base64 data URLs and passed back to React Native via the WebView message bridge
+
+3. **Customization**: The component supports extensive customization through props that modify the injected HTML/CSS/JS
+
+## Common Development Commands
+
+### Example Apps
+The repository contains multiple example applications for different use cases:
+
+```bash
+# React Native CLI app with TypeScript
+cd example/signapp && npm run android
+cd example/signapp && npm run ios
+
+# Expo app with modern Expo Router
+cd example/expo-app && npm start
+cd example/expo-app && npm run android
+cd example/expo-app && npm run ios
+
+# Basic React Native CLI app
+cd example/exampleApp && npm start
+```
+
+### Testing
+```bash
+# Run tests in example apps
+cd example/signapp && npm test
+cd example/expo-app && npm test
+```
+
+### Linting
+```bash
+# Lint example apps
+cd example/signapp && npm run lint
+cd example/expo-app && npm run lint
+```
+
+## Development Notes
+
+### Modifying the Core Component
+- The main component logic is in `index.js`
+- WebView HTML template is in `h5/html.js` 
+- JavaScript functionality is split between `h5/js/signature_pad.js` and `h5/js/app.js`
+
+### Adding New Features
+1. Add props to the main component interface
+2. Update TypeScript definitions in `index.d.ts`
+3. Modify the HTML template in `h5/html.js` if UI changes are needed
+4. Update the injected JavaScript in `h5/js/app.js` for new functionality
+5. Test across multiple example apps to ensure compatibility
+
+### Example App Structure
+- `signapp/`: Full React Native CLI app with TypeScript and Jest testing
+- `expo-app/`: Modern Expo app with Expo Router and TypeScript
+- `exampleApp/`: Basic React Native CLI app
+- `expo-app1/`, `signapp1/`, `sign-app/`, `ts-expo/`: Various other example configurations
+
+### Dependencies
+- Main library only has peer dependency on `react-native-webview`
+- Example apps include additional dependencies for testing and development
+- No build process required for the main library (it's a pure React Native component)

package/QUICK_START.md

@@ -0,0 +1,219 @@
+# Quick Start Guide
+
+Get up and running with `react-native-signature-canvas` in minutes!
+
+## 🚀 Installation
+
+```bash
+# Install the package
+npm install react-native-signature-canvas
+
+# For React Native CLI projects, also install WebView
+npm install react-native-webview
+cd ios && pod install # iOS only
+```
+
+## 📱 Basic Example
+
+```jsx
+import React, { useRef, useState } from 'react';
+import { View, Button, StyleSheet } from 'react-native';
+import SignatureCanvas from 'react-native-signature-canvas';
+
+export default function App() {
+  const ref = useRef();
+  const [signature, setSignature] = useState();
+
+  const handleOK = (signature) => {
+    console.log(signature);
+    setSignature(signature);
+  };
+
+  const handleClear = () => {
+    ref.current?.clearSignature();
+  };
+
+  const handleSave = () => {
+    ref.current?.readSignature();
+  };
+
+  return (
+    <View style={styles.container}>
+      <SignatureCanvas
+        ref={ref}
+        onOK={handleOK}
+        onEmpty={() => console.log('Empty')}
+        descriptionText="Sign here"
+        clearText="Clear"
+        confirmText="Save"
+        style={styles.signature}
+      />
+      
+      <View style={styles.buttons}>
+        <Button title="Clear" onPress={handleClear} />
+        <Button title="Save" onPress={handleSave} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+  },
+  signature: {
+    flex: 1,
+    borderColor: '#000033',
+    borderWidth: 1,
+  },
+  buttons: {
+    flexDirection: 'row',
+    justifyContent: 'space-around',
+    marginTop: 20,
+  },
+});
+```
+
+## ⚡ Enhanced Example with New Features
+
+```jsx
+import React, { useRef, useState } from 'react';
+import { View, Button, StyleSheet, Alert } from 'react-native';
+import SignatureCanvas from 'react-native-signature-canvas';
+
+export default function EnhancedSignatureApp() {
+  const ref = useRef();
+  const [signature, setSignature] = useState();
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleSignature = (signature) => {
+    setSignature(signature);
+    setIsLoading(false);
+    Alert.alert('Success', 'Signature saved!');
+  };
+
+  const handleEmpty = () => {
+    setIsLoading(false);
+    Alert.alert('Empty', 'Please draw a signature first');
+  };
+
+  const handleError = (error) => {
+    setIsLoading(false);
+    Alert.alert('Error', error.message);
+  };
+
+  const handleSave = () => {
+    setIsLoading(true);
+    ref.current?.readSignature();
+  };
+
+  return (
+    <View style={styles.container}>
+      <SignatureCanvas
+        ref={ref}
+        onOK={handleSignature}
+        onEmpty={handleEmpty}
+        onError={handleError}
+        descriptionText="Sign here"
+        clearText="Clear"
+        confirmText={isLoading ? "Saving..." : "Save"}
+        penColor="#0066cc"
+        backgroundColor="rgba(255,255,255,0)"
+        // NEW: WebView customization
+        webviewProps={{
+          cacheEnabled: true,
+          androidLayerType: "hardware",
+        }}
+        style={styles.signature}
+      />
+      
+      <View style={styles.controls}>
+        <Button 
+          title="Clear" 
+          onPress={() => ref.current?.clearSignature()} 
+        />
+        <Button 
+          title="Undo" 
+          onPress={() => ref.current?.undo()} 
+        />
+        <Button 
+          title="Save" 
+          onPress={handleSave}
+          disabled={isLoading}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#f5f5f5',
+    padding: 20,
+  },
+  signature: {
+    flex: 1,
+    borderColor: '#ddd',
+    borderWidth: 1,
+    borderRadius: 8,
+    backgroundColor: 'white',
+  },
+  controls: {
+    flexDirection: 'row',
+    justifyContent: 'space-around',
+    marginTop: 20,
+    paddingVertical: 10,
+  },
+});
+```
+
+## 🔧 Common Configurations
+
+### High Performance Setup
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: true,
+    androidLayerType: "hardware",
+    androidHardwareAccelerationDisabled: false,
+  }}
+/>
+```
+
+### Low Memory Setup
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: false,
+    androidLayerType: "software", 
+    androidHardwareAccelerationDisabled: true,
+  }}
+/>
+```
+
+### Security Focused Setup
+```jsx
+<SignatureCanvas
+  webviewProps={{
+    allowFileAccess: false,
+    allowFileAccessFromFileURLs: false,
+    mixedContentMode: "never",
+    allowsLinkPreview: false,
+  }}
+/>
+```
+
+## 📖 Next Steps
+
+- [Read the full documentation](./README.md)
+- [Learn about WebView customization](./WEBVIEW_PROPS.md)
+- [Check out example apps](./example/)
+- [View TypeScript definitions](./index.d.ts)
+
+## 🆘 Need Help?
+
+- [Check troubleshooting guide](./README.md#troubleshooting)
+- [View common issues](https://github.com/YanYuanFE/react-native-signature-canvas/issues)
+- [Ask questions in discussions](https://github.com/YanYuanFE/react-native-signature-canvas/discussions)

package/README.md

@@ -10,14 +10,19 @@ A React Native component for capturing signatures or drawing on a canvas with a
 
 ## Features
 
-- Cross-platform support (iOS, Android, Expo)
-- Smooth, responsive drawing experience
-- Customizable pen color, size, and background
-- Support for background and overlay images
-- Export signatures as PNG, JPEG, or SVG
-- Undo/redo functionality
-- Drawing and erasing modes
-- TypeScript support
+- ✅ **Cross-platform support** (iOS, Android, Expo)
+- ✅ **Smooth, responsive drawing experience** with optimized performance
+- ✅ **Customizable pen color, size, and background**
+- ✅ **Support for background and overlay images**
+- ✅ **Export signatures** as PNG, JPEG, or SVG
+- ✅ **Undo/redo functionality**
+- ✅ **Drawing and erasing modes**
+- ✅ **Full TypeScript support** with enhanced type definitions
+- 🆕 **Advanced error handling** with automatic recovery
+- 🆕 **Performance monitoring** and optimization
+- 🆕 **Flexible WebView customization** via `webviewProps`
+- 🆕 **Enhanced security** with configurable restrictions
+- 🆕 **Memory management** and leak prevention
 
 ## Installation
 
@@ -55,23 +60,33 @@ import SignatureCanvas from 'react-native-signature-canvas';
 
 const SignatureScreen = () => {
   const [signature, setSignature] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
   const ref = useRef();
 
   const handleSignature = (signature) => {
-    console.log(signature);
+    console.log('Signature captured:', signature);
     setSignature(signature);
+    setIsLoading(false);
   };
 
   const handleEmpty = () => {
-    console.log('Empty');
+    console.log('Signature is empty');
+    setIsLoading(false);
   };
 
   const handleClear = () => {
-    console.log('Clear success!');
+    console.log('Signature cleared');
+    setSignature(null);
+  };
+
+  const handleError = (error) => {
+    console.error('Signature pad error:', error);
+    setIsLoading(false);
   };
 
   const handleEnd = () => {
-    ref.current.readSignature();
+    setIsLoading(true);
+    ref.current?.readSignature();
   };
 
   return (
@@ -91,10 +106,18 @@ const SignatureScreen = () => {
         onOK={handleSignature}
         onEmpty={handleEmpty}
         onClear={handleClear}
+        onError={handleError}
         autoClear={true}
         descriptionText="Sign here"
         clearText="Clear"
-        confirmText="Save"
+        confirmText={isLoading ? "Processing..." : "Save"}
+        penColor="#000000"
+        backgroundColor="rgba(255,255,255,0)"
+        webviewProps={{
+          // Custom WebView optimization
+          cacheEnabled: true,
+          androidLayerType: "hardware",
+        }}
       />
     </View>
   );
@@ -162,6 +185,8 @@ export default SignatureScreen;
 | `webStyle` | `string` | - | WebView style to override default style |
 | `webviewContainerStyle` | `object` | - | Style for the WebView container |
 | `androidLayerType` | `none\|software\|hardware` | `hardware` | Sets the Android WebView layer type |
+| `onError` | `function` | - | Callback when an error occurs |
+| `webviewProps` | `object` | `{}` | Additional props to pass to the underlying WebView |
 
 ## Methods
 
@@ -179,6 +204,76 @@ Access these methods using a ref to the SignatureCanvas component.
 | `undo()` | Undo last stroke |
 | `redo()` | Redo last stroke |
 
+## WebView Customization (New!)
+
+The `webviewProps` parameter allows you to customize the underlying WebView behavior while maintaining signature functionality:
+
+```jsx
+<SignatureCanvas
+  // ... other props
+  webviewProps={{
+    // Performance optimization
+    cacheEnabled: true,
+    androidLayerType: "hardware",
+    androidHardwareAccelerationDisabled: false,
+    
+    // Security settings
+    allowFileAccess: false,
+    allowFileAccessFromFileURLs: false,
+    mixedContentMode: "never",
+    
+    // UI customization
+    decelerationRate: 'fast',
+    bounces: false,
+    
+    // Any other WebView props...
+  }}
+/>
+```
+
+### Performance Optimization Examples
+
+```jsx
+// High-performance mode
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: true,
+    androidLayerType: "hardware",
+    androidHardwareAccelerationDisabled: false,
+  }}
+/>
+
+// Low-memory mode
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: false,
+    androidLayerType: "software",
+    androidHardwareAccelerationDisabled: true,
+  }}
+/>
+```
+
+## Error Handling (Enhanced!)
+
+```jsx
+const [error, setError] = useState(null);
+
+const handleError = (error) => {
+  console.error('Signature error:', error);
+  setError(error.message);
+  // Error recovery is automatic, but you can handle it here
+};
+
+<SignatureCanvas
+  onError={handleError}
+  // Component automatically retries on recoverable errors
+/>
+
+{error && (
+  <Text style={{ color: 'red' }}>Error: {error}</Text>
+)}
+```
+
 ## Advanced Usage
 
 ### Using a Background Image
@@ -304,12 +399,162 @@ const styles = StyleSheet.create({
 });
 ```
 
+## Performance & Reliability
+
+### Automatic Error Recovery
+- **Smart retry logic** with exponential backoff
+- **Circuit breaker pattern** to prevent cascading failures  
+- **Memory leak prevention** with automatic cleanup
+- **Performance monitoring** with automatic optimization
+
+### Performance Features
+- **Debounced resize handling** for smooth interaction
+- **Memory pressure detection** with adaptive optimization
+- **Optimized rendering** with reduced re-renders
+- **Device-specific optimization** based on hardware capabilities
+
+### Security Enhancements
+- **Configurable WebView security** via `webviewProps`
+- **Input validation** for all methods and callbacks
+- **XSS protection** with content security policies
+- **File access restrictions** by default
+
+## Migration Guide
+
+### From v4.6.x to v4.7.x
+
+This version is fully backward compatible. New features:
+
+```jsx
+// NEW: Enhanced error handling
+<SignatureCanvas
+  onError={(error) => console.error(error)} // New callback
+/>
+
+// NEW: WebView customization
+<SignatureCanvas
+  webviewProps={{ // New prop
+    cacheEnabled: false,
+    androidLayerType: "software"
+  }}
+/>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Signature pad not loading
+```jsx
+// Solution: Add error handling and check WebView props
+<SignatureCanvas
+  onError={(error) => console.log('Error:', error)}
+  onLoadEnd={() => console.log('Loaded successfully')}
+  webviewProps={{
+    startInLoadingState: true,
+    renderLoading: () => <ActivityIndicator />
+  }}
+/>
+```
+
+**Issue**: Poor performance on older devices
+```jsx
+// Solution: Use low-performance mode
+<SignatureCanvas
+  webviewProps={{
+    androidLayerType: "software",
+    androidHardwareAccelerationDisabled: true,
+    cacheEnabled: false
+  }}
+/>
+```
+
+**Issue**: Memory issues
+```jsx
+// Solution: The component now handles this automatically
+// But you can customize via webviewProps if needed
+<SignatureCanvas
+  webviewProps={{
+    cacheEnabled: false, // Reduce memory usage
+    androidLayerType: "software" // Use software rendering
+  }}
+/>
+```
+
+## API Reference
+
+For detailed API documentation, see:
+- [WEBVIEW_PROPS.md](./WEBVIEW_PROPS.md) - WebView customization guide
+- [TypeScript definitions](./index.d.ts) - Complete type definitions
+
 ## Core Technology
 
 This component is built on:
 - [signature_pad.js](https://github.com/szimek/signature_pad) for the core signature functionality
 - React Native WebView for cross-platform rendering
+- Enhanced with performance monitoring and error recovery systems
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve this component.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/YanYuanFE/react-native-signature-canvas.git
+
+# Install dependencies
+cd react-native-signature-canvas
+npm install
+
+# Run example apps
+cd example/expo-app
+npm install && npm start
+```
+
+## Changelog
+
+### v4.7.x (Latest)
+- 🆕 Added `webviewProps` for WebView customization
+- 🆕 Enhanced error handling with automatic recovery
+- 🆕 Performance monitoring and optimization
+- 🆕 Memory leak prevention
+- 🆕 Improved TypeScript definitions
+- 🔧 Fixed global variable pollution in WebView JavaScript
+- 🔧 Added input validation for all methods
+- ⚡ Optimized rendering performance
+
+[View full changelog](./CHANGELOG.md)
 
 ## License
 
-MIT
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+
+## Buy Me a Coffee ☕
+
+If you find this project helpful, consider supporting its development with cryptocurrency donations:
+
+### Cryptocurrency Donations
+
+| Currency | Address | QR Code |
+|----------|---------|----------|
+| **Bitcoin (BTC)** | `bc1phyz9agr0m9l2w9pd8w85w4da2jt3wl4cre7vv0qq4uesm3fv00pscu96tux` | ![BTC QR](https://api.qrserver.com/v1/create-qr-code/?size=100x100&data=bc1phyz9agr0m9l2w9pd8w85w4da2jt3wl4cre7vv0qq4uesm3fv00pscu96tux) |
+| **Ethereum (ETH)** | `0xf5dfe16b1e64e8e3a92063fb2922447e13b48945` | ![ETH QR](https://api.qrserver.com/v1/create-qr-code/?size=100x100&data=0xf5dfe16b1e64e8e3a92063fb2922447e13b48945) |
+| **Solana (SOL)** | `3VuhyeTj3hMSrmzq7NctHkgFxvJrmtAUQTzagEBEu3Vm` | ![SOL QR](https://api.qrserver.com/v1/create-qr-code/?size=100x100&data=3VuhyeTj3hMSrmzq7NctHkgFxvJrmtAUQTzagEBEu3Vm) |
+
+
+### Other Ways to Support
+
+- ⭐ Star this repository
+- 🐛 Report bugs and issues
+- 💡 Suggest new features
+- 🤝 Contribute code improvements
+- 📢 Share this project with others
+
+Your support helps maintain and improve this open-source project. Thank you! 🙏
+
+---
+
+**Made with ❤️ for the React Native community**