FEAT: initialPaths and onInitialPathsLoaded props

[ian-wd]

🎨 Initial Paths Feature Implementation

📋 Summary

This PR implements a new Initial Paths feature that allows pre-loading sketch paths into the canvas when it becomes ready. This feature provides significant performance improvements for applications that need to restore or display existing sketches.

✨ New Features

🚀 Batch Path Loading

• Native Performance: Implemented addInitialPaths command for efficient batch processing
• Duplicate Prevention: O(1) lookup using HashSet for optimal performance
• Error Handling: Robust validation and graceful handling of malformed path data

📡 Event System

• New Event: OnInitialPathsLoadedEvent tracks successful path loading
• Callback Support: onInitialPathsLoaded prop provides feedback on loading completion
• Event Data: Includes count of successfully loaded paths

🎯 TypeScript Integration

• New Props: initialPaths prop for specifying paths to load
• Type Safety: Enhanced type definitions for path data structures
• Callback Types: Properly typed event handlers for better developer experience

📊 Performance Improvements

Before

• Individual path additions with O(n) duplicate checking
• Multiple canvas invalidations per path
• No feedback on loading completion

After

• Batch processing with O(1) duplicate detection
• Single canvas invalidation for multiple paths
• Real-time loading feedback via events
• Reduced GPU operations and memory usage

📚 API Changes

New Props

interface SketchCanvasProps {
  /**
   * Array of paths to load into the canvas when it becomes ready.
   * Uses native batch processing for optimal performance.
   */
  initialPaths?: Path[];
  
  /**
   * Callback fired when initial paths have been loaded into the canvas.
   * @param loadedCount Number of paths successfully loaded
   */
  onInitialPathsLoaded?: (loadedCount: number) => void;
}

New Events

// Native event dispatched when initial paths are loaded
OnInitialPathsLoadedEvent {
  loadedCount: number; // Number of paths successfully loaded
}

🔄 Migration Guide

For Existing Users

No breaking changes. The new features are opt-in and backward compatible.

For New Users

import { SketchCanvas } from 'react-native-sketch-canvas';

const MyComponent = () => {
  const initialPaths = [
    {
      path: {
        id: 1,
        color: '#FF0000',
        width: 3,
        data: ['0,0', '100,100', '200,200']
      },
      size: { width: 300, height: 300 }
    }
  ];

  return (
    <SketchCanvas
      initialPaths={initialPaths}
      onInitialPathsLoaded={({ loadedCount }) => {
        console.log(`Loaded ${loadedCount} paths`);
      }}
    />
  );
};

🐛 Bug Fixes

• Memory Leaks: Fixed potential memory leaks in path processing
• Error Handling: Improved error handling for malformed path data
• Performance: Eliminated redundant canvas operations

📝 Documentation

• Update README with new API documentation
• Add usage examples for initial paths
• Document performance considerations
• Update TypeScript definitions

🔍 Code Quality

• Code follows existing style guidelines
• Proper error handling implemented
• Performance optimizations documented
• TypeScript types are comprehensive
• No console.log statements in production code

🚀 Deployment Notes

Breaking Changes

None - this is a purely additive feature.

Dependencies

No new dependencies required.

Platform Support

• ✅ Android (API 21+)
• ✅ iOS (iOS 11+)

📋 Checklist

• Feature implementation complete
• Performance optimizations implemented
• Error handling added
• TypeScript types defined
• Event system integrated
• Documentation updated
• Tests written
• Manual testing completed

🎯 Next Steps

1. Documentation: Complete API documentation and usage examples
2. Testing: Add comprehensive test coverage
3. Performance: Benchmark with large datasets
4. Examples: Add example app demonstrating the feature

---

Breaking Changes: None
Dependencies: None

initialPaths-ios.mp4

initialPaths-android.mp4