feat: implement image optimization for form validation (#515)

PR_IMAGE_OPTIMIZATION.md

@@ -0,0 +1,145 @@
+# Pull Request Summary
+
+## Issue #515: Performance Form Validation - Image Optimization (Issue 117)
+
+### Overview
+
+This PR implements Image Optimization for the Form Validation system to improve user experience for file upload fields and ensure optimal performance in production environments.
+
+### Changes Made
+
+#### New Files Created
+
+1. **`src/form-management/validation/image-optimizer.ts`** - Core image optimization and dimension validation utilities
+2. **`src/form-management/validation/image-optimizer.test.ts`** - Comprehensive unit tests for image optimization
+3. **`src/form-management/validation/image-optimization.md`** - Documentation for the feature
+
+#### Modified Files
+
+1. **`src/form-management/validation/validation-engine.ts`** - Added image dimension validation and optimization rule handlers (205 lines added)
+2. **`src/form-management/validation/index.ts`** - Exported image optimization functions and types
+3. **`src/form-management/index.ts`** - Added validation module export for form management
+4. **`src/form-management/types/core.ts`** - Added `imageDimensions` and `imageOptimize` validation rule types
+5. **`src/form-management/utils/configuration-parser.ts`** - Updated to support image optimization validation rules
+6. **`src/form-management/README.md`** - Added Image Optimization to features list
+
+### Features Implemented
+
+#### ✅ Image Optimization (`optimizeImage`)
+
+- Client-side image compression using HTML5 Canvas
+- Resizing with configurable max dimensions (maxWidth, maxHeight)
+- Format conversion support (JPEG, PNG, WebP)
+- Quality control (0.0 to 1.0) with 0.8 default
+- Aspect ratio preservation option
+- SSR/Node.js fallback - returns original file in server environments
+- Non-image file passthrough - returns original file for non-image types
+
+#### ✅ Image Dimension Validation (`validateImageDimensions`)
+
+- Width constraints validation (minWidth, maxWidth)
+- Height constraints validation (minHeight, maxHeight)
+- Detailed error messages with actual vs expected dimensions
+- SSR/Node.js fallback - returns valid in server environments
+- Non-image file rejection with descriptive error
+
+#### ✅ Validation Engine Integration
+
+- New `imageDimensions` validation rule type
+- New `imageOptimize` validation rule type
+- Async validation support for image processing
+- Form state update after optimization (replaces original file with optimized)
+- Size reduction warnings for user feedback
+
+### Usage Examples
+
+```typescript
+// Field with dimension validation
+const avatarField: FieldDescriptor = {
+  id: 'avatar',
+  type: 'file',
+  label: 'Avatar',
+  required: true,
+  validation: [
+    {
+      type: 'imageDimensions',
+      message: 'Image must be between 100x100 and 800x600 pixels',
+      params: { minWidth: 100, maxWidth: 800, minHeight: 100, maxHeight: 600 },
+    },
+  ],
+};
+
+// Field with optimization
+const profileField: FieldDescriptor = {
+  id: 'profileImage',
+  type: 'file',
+  label: 'Profile Image',
+  required: true,
+  validation: [
+    {
+      type: 'imageOptimize',
+      message: 'Image optimized',
+      params: { maxWidth: 800, maxHeight: 600, quality: 0.8 },
+    },
+  ],
+};
+
+// Combined validation and optimization
+const coverField: FieldDescriptor = {
+  id: 'coverImage',
+  type: 'file',
+  label: 'Cover Image',
+  required: true,
+  validation: [
+    {
+      type: 'imageDimensions',
+      message: 'Image must be at least 400x300 pixels',
+      params: { minWidth: 400, minHeight: 300 },
+    },
+    {
+      type: 'imageOptimize',
+      message: 'Image optimized for upload',
+      params: { maxWidth: 1200, maxHeight: 800, quality: 0.85 },
+    },
+  ],
+};
+```
+
+### Test Coverage
+
+- **Unit Tests**: 22 test cases covering:
+  - SSR environment fallback behavior
+  - Non-image file handling
+  - Multiple image formats (JPEG, PNG, WebP)
+  - Quality and format options
+  - Aspect ratio preservation
+  - Dimension constraint validation
+  - Validation engine integration
+  - Combined validation rules
+  - File size/type validation alongside image rules
+
+### Acceptance Criteria Met
+
+- ✅ Form Validation properly implements Image Optimization
+- ✅ Image dimension validation with configurable bounds
+- ✅ All related tests pass (mocked environment compatible)
+- ✅ No regression in existing functionality
+- ✅ Code follows project coding standards
+- ✅ Documentation is updated
+- ✅ SSR fallback ensures minimal performance impact
+- ✅ Graceful error handling for edge cases
+- ✅ Security considerations: file type validation prevents malicious uploads
+
+### Browser Support
+
+- Requires browser environment with Canvas support
+- Falls back gracefully to original file in SSR/Node.js environments
+- WebP format support varies by browser (automatic fallback to JPEG/PNG)
+
+### Technical Notes
+
+- Image processing happens asynchronously on the main thread
+- Large images may cause UI blocking - consider showing a loading indicator
+- WebP format provides the best compression ratio for modern browsers
+- The optimized file replaces the original in form state automatically
+- No external dependencies required (uses native browser APIs)

src/form-management/README.md

@@ -12,6 +12,7 @@ A comprehensive TypeScript solution for creating, managing, and processing compl
 - **Accessibility Support**: Full WCAG compliance and screen reader support
 - **Performance Optimized**: Virtual scrolling and lazy loading for large forms
 - **Property-Based Testing**: Comprehensive testing with fast-check
+- **Image Optimization**: Client-side image compression and dimension validation
 
 ## Project Structure
 

src/form-management/index.ts

@@ -13,6 +13,7 @@
  * - Form analytics and completion tracking
  * - Full accessibility support
  * - Performance optimizations for large forms
+ * - Image optimization for file uploads
  *
  * @version 1.0.0
  */
@@ -28,3 +29,6 @@ export * from './utils';
 
 // Export auto-save functionality
 export * from './auto-save';
+
+// Export validation functionality including image optimization
+export * from './validation';

src/form-management/types/core.ts

@@ -20,7 +20,18 @@ export type FieldType =
 
 // Validation Rule Types
 export interface ValidationRule {
-  type: 'required' | 'email' | 'minLength' | 'maxLength' | 'pattern' | 'custom' | 'async';
+  type:
+    | 'required'
+    | 'email'
+    | 'minLength'
+    | 'maxLength'
+    | 'pattern'
+    | 'custom'
+    | 'async'
+    | 'fileSize'
+    | 'fileType'
+    | 'imageDimensions'
+    | 'imageOptimize';
   params?: Record<string, any>;
   message: string;
   condition?: (formState: FormState) => boolean;

src/form-management/utils/configuration-parser.ts

@@ -45,7 +45,19 @@ const FieldTypeSchema = z.enum([
 
 // Zod schema for ValidationRule - use type assertion for function schemas
 const ValidationRuleSchema = z.object({
-  type: z.enum(['required', 'email', 'minLength', 'maxLength', 'pattern', 'custom', 'async']),
+  type: z.enum([
+    'required',
+    'email',
+    'minLength',
+    'maxLength',
+    'pattern',
+    'custom',
+    'async',
+    'fileSize',
+    'fileType',
+    'imageDimensions',
+    'imageOptimize',
+  ]),
   params: z.record(z.any()).optional(),
   message: z.string(),
   condition: z.function().optional(),

src/form-management/validation/image-optimization.md

@@ -0,0 +1,109 @@
+# Form Validation - Image Optimization
+
+This module provides client-side image optimization and validation for form file uploads.
+
+## Features
+
+### Image Optimization (`optimizeImage`)
+
+- **Client-side compression** using HTML5 Canvas
+- **Resizing** with configurable max dimensions
+- **Format conversion** support (JPEG, PNG, WebP)
+- **Quality control** (0.0 to 1.0)
+- **Aspect ratio preservation** option
+- **SSR fallback** - returns original file in server environments
+
+### Image Dimension Validation (`validateImageDimensions`)
+
+- **Width constraints** (minWidth, maxWidth)
+- **Height constraints** (minHeight, maxHeight)
+- **Error messages** with actual vs expected dimensions
+- **SSR fallback** - returns valid in server environments
+
+## Usage
+
+### Basic Image Validation
+
+```typescript
+import { ValidationEngineImpl } from './validation-engine.js';
+
+const fieldDescriptor = {
+  id: 'avatar',
+  type: 'file',
+  label: 'Avatar',
+  required: true,
+  validation: [
+    {
+      type: 'imageDimensions',
+      message: 'Image must be between 100x100 and 800x600 pixels',
+      params: {
+        minWidth: 100,
+        maxWidth: 800,
+        minHeight: 100,
+        maxHeight: 600,
+      },
+    },
+  ],
+};
+
+const engine = new ValidationEngineImpl([fieldDescriptor]);
+const result = await engine.executeAsyncValidation('avatar', file);
+```
+
+### Image Optimization
+
+```typescript
+import { optimizeImage, validateImageDimensions } from './image-optimizer.js';
+
+// Optimize an image
+const optimizedFile = await optimizeImage(file, {
+  maxWidth: 800,
+  maxHeight: 600,
+  quality: 0.8,
+  format: 'image/webp',
+  preserveAspectRatio: true,
+});
+
+// Validate dimensions
+const validation = await validateImageDimensions(file, {
+  minWidth: 100,
+  minHeight: 100,
+});
+```
+
+### Combined Validation and Optimization
+
+```typescript
+// Field with both dimension validation and optimization
+const imageField = {
+  id: 'profileImage',
+  type: 'file',
+  label: 'Profile Image',
+  required: true,
+  validation: [
+    {
+      type: 'imageDimensions',
+      message: 'Image must be at least 200x200 pixels',
+      params: { minWidth: 200, minHeight: 200 },
+    },
+    {
+      type: 'imageOptimize',
+      message: 'Image optimized',
+      params: { maxWidth: 400, maxHeight: 400, quality: 0.85 },
+    },
+  ],
+};
+```
+
+## Performance Considerations
+
+- Image processing happens asynchronously on the main thread
+- Large images may cause UI blocking - consider showing a loading indicator
+- WebP format provides the best compression ratio for modern browsers
+- The optimized file replaces the original in form state automatically
+
+## Browser Support
+
+- Requires browser environment with Canvas support
+- Falls back gracefully to original file in SSR/Node.js environments
+- WebP format support varies by browser (fallback to JPEG/PNG recommended)