@visns-studio/visns-components 5.14.0 → 5.14.2

package/src/components/generic/OcrTemplateEnhanced.md

@@ -0,0 +1,249 @@
+# Enhanced OCR Template Component
+
+## Overview
+
+The `OcrTemplateEnhanced` component provides a modern, user-friendly interface for OCR document processing with intelligent data categorization and template building capabilities.
+
+## Key Improvements Over Original OCR Template
+
+### 🎯 **User Experience Enhancements**
+
+1. **Modern Drag-and-Drop Interface**
+   - Visual drop zones with hover effects
+   - File validation and size limits (10MB)
+   - Support for PDF, JPG, PNG formats
+   - File preview with metadata display
+
+2. **Real-Time Processing Feedback**
+   - Multi-stage progress indicators
+   - Visual status updates (Upload → OCR → Analysis)
+   - Progress bars for upload stage
+   - Loading animations and status icons
+
+3. **Smart Data Categorization**
+   - Automatic categorization into 5 groups:
+     - 📞 Contact Information (email, phone, names)
+     - 💰 Financial Data (amounts, prices, costs)
+     - 📅 Dates & Times (dates, timestamps)
+     - 🔢 Identifiers (IDs, numbers, references)
+     - 📄 Other Data (miscellaneous key-value pairs)
+
+4. **Card-Based Data Organization**
+   - Interactive data cards with confidence scoring
+   - Color-coded categories with icons
+   - Visual selection states with hover effects
+   - Confidence badges (High/Medium/Low)
+
+### 🤖 **Intelligent Features**
+
+1. **Template Suggestions**
+   - Auto-generated templates based on detected document type
+   - Pre-built templates for invoices, contracts, quotes
+   - One-click template application
+
+2. **Smart Variable Management**
+   - Clickable variable chips for easy insertion
+   - Live filename preview
+   - Template validation and formatting
+
+3. **Enhanced Document Analysis**
+   - Improved text line organization
+   - Better title selection interface
+   - Grid-based layout for better readability
+
+## Component Usage
+
+### Basic Implementation
+
+```jsx
+import { OcrTemplateEnhanced } from '@visns-studio/visns-components';
+
+<OcrTemplateEnhanced 
+  id="ocr_template_1"
+  data={formData}
+  setData={setFormData}
+  routeParams={routeParams}
+  urlParam="id"
+  onSave={handleSave}
+/>
+```
+
+### Integration in GenericDetail
+
+The component automatically replaces the original OCR template when `type: 'ocrTemplate'` is used in GenericDetail configuration:
+
+```javascript
+{
+  id: 'document_processor',
+  type: 'ocrTemplate',
+  label: 'Document OCR Processing'
+}
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | string | ✅ | Unique identifier for the OCR template instance |
+| `data` | object | ✅ | Form data object containing OCR results |
+| `setData` | function | ✅ | State setter function for updating form data |
+| `routeParams` | object | ✅ | Route parameters from React Router |
+| `urlParam` | string | ✅ | URL parameter key for template ID |
+| `onSave` | function | ✅ | Callback function for saving template configuration |
+
+## Data Structure
+
+### Expected Data Format
+
+```javascript
+{
+  [id]: {
+    keyValuePairs: {
+      "invoice_number": "INV-001",
+      "amount": "1500.00",
+      "date": "2025-01-15",
+      "client_name": "ACME Corp"
+    },
+    allText: [
+      "INVOICE INV-001",
+      "Date: 2025-01-15",
+      "Amount: $1,500.00",
+      "Client: ACME Corp"
+    ],
+    selectedKey: ["invoice_number", "amount"],
+    selectedTitle: ["INVOICE INV-001"],
+    dynamicFilename: "INV_{{invoice_number}}_{{date}}",
+    uploadedFile: {
+      name: "invoice.pdf",
+      size: 524288,
+      type: "application/pdf"
+    }
+  }
+}
+```
+
+## API Integration
+
+### OCR Processing Endpoint
+
+```
+POST /ajax/ocr/analyzeFile
+```
+
+**Request:**
+- `file`: Document file (PDF/JPG/PNG)
+- `template_id`: Template identifier
+
+**Response:**
+```javascript
+{
+  keyValuePairs: { /* extracted key-value pairs */ },
+  allText: [ /* array of text lines */ ]
+}
+```
+
+## Styling & Customization
+
+### CSS Classes
+
+The component uses CSS modules with the following key classes:
+
+- `.ocrTemplateContainer` - Main container
+- `.dropZone` - File upload area
+- `.dataCard` - Individual data cards
+- `.processingStep` - Progress indicator steps
+- `.templateBuilder` - Template configuration section
+
+### Category Colors
+
+- Contact: `#17a2b8` (Info blue)
+- Financial: `#28a745` (Success green)
+- Dates: `#ffc107` (Warning yellow)
+- Identifiers: `#6f42c1` (Purple)
+- Other: `#6c757d` (Gray)
+
+## Advanced Features
+
+### Template Suggestions
+
+The component automatically suggests templates based on detected data patterns:
+
+```javascript
+// Auto-detected invoice pattern
+{
+  name: "Invoice Template",
+  filename: "INV_{{invoice_number}}_{{date}}",
+  description: "Standard invoice naming convention"
+}
+```
+
+### Confidence Scoring
+
+Each extracted key-value pair includes a confidence score:
+
+- **High (80%+)**: Green badge, reliable data
+- **Medium (60-79%)**: Yellow badge, moderate confidence
+- **Low (<60%)**: Red badge, requires verification
+
+### Responsive Design
+
+- Mobile-optimized with single-column layouts
+- Touch-friendly interface elements
+- Adaptive grid systems for different screen sizes
+
+## Migration Guide
+
+### From Original OCR Template
+
+The enhanced component is a drop-in replacement. No configuration changes required:
+
+**Before:**
+```javascript
+// Old table-based interface with basic file input
+case 'ocrTemplate':
+  return renderOcrTemplate(id);
+```
+
+**After:**
+```javascript
+// New enhanced component with modern UI
+case 'ocrTemplate':
+  return (
+    <OcrTemplateEnhanced 
+      id={id}
+      data={data}
+      setData={setData}
+      routeParams={routeParams}
+      urlParam={urlParam}
+      onSave={handleOcrTemplateSave}
+    />
+  );
+```
+
+### Backward Compatibility
+
+- All existing data structures remain compatible
+- Original API endpoints work unchanged
+- Existing templates continue to function
+- State management patterns preserved
+
+## Performance Considerations
+
+- File size validation (10MB limit)
+- Optimized re-rendering with React.memo patterns
+- Debounced template preview updates
+- Efficient categorization algorithms
+
+## Accessibility
+
+- ARIA labels for all interactive elements
+- Keyboard navigation support
+- Screen reader compatible
+- High contrast mode support
+- Focus management for modal states
+
+---
+
+## Support
+
+For technical support or feature requests, please refer to the main component library documentation or contact the development team.