@visns-studio/visns-components 5.11.4 → 5.11.6

package/README.md

@@ -951,6 +951,766 @@ File upload component with drag and drop support.
 />
 ```
 
+### Association Management Components
+
+#### AssociationManager
+
+A sophisticated component for managing entity relationships and associations within your application. The AssociationManager provides an intuitive interface for creating, viewing, and managing complex many-to-many relationships between different data entities.
+
+```jsx
+<AssociationManager
+    config={{
+        title: "Client Associations",
+        description: "Manage relationships between clients and projects",
+        primaryEntity: {
+            id: "clients",
+            label: "Clients",
+            displayKey: "name",
+            fetchUrl: "/api/clients"
+        },
+        secondaryEntity: {
+            id: "projects", 
+            label: "Projects",
+            displayKey: "title",
+            fetchUrl: "/api/projects"
+        },
+        association: {
+            fetchUrl: "/api/client-project-associations",
+            createUrl: "/api/client-project-associations",
+            deleteUrl: "/api/client-project-associations",
+            pivotTable: "client_project"
+        },
+        permissions: {
+            canCreate: true,
+            canDelete: true,
+            canView: true
+        },
+        ui: {
+            searchPlaceholder: "Search clients or projects...",
+            emptyStateMessage: "No associations found",
+            confirmDeleteMessage: "Are you sure you want to remove this association?"
+        }
+    }}
+    userProfile={userProfile}
+    onAssociationChange={(data) => console.log('Association changed:', data)}
+/>
+```
+
+**Key Features:**
+
+1. **Bidirectional Relationship Management**:
+   - Create associations from either entity perspective
+   - Automatic relationship synchronization
+   - Real-time updates across related views
+
+2. **Advanced Search and Filtering**:
+   - Multi-entity search capabilities
+   - Filter by entity type, status, or custom attributes
+   - Debounced search to optimize performance
+
+3. **Bulk Operations**:
+   - Select multiple entities for batch association
+   - Bulk delete with confirmation dialogs
+   - Mass import/export functionality
+
+4. **Visual Association Mapping**:
+   - Interactive relationship visualization
+   - Drag-and-drop association creation
+   - Color-coded entity types
+
+5. **Permission-Based Access Control**:
+   - Granular permissions for create, read, update, delete
+   - Role-based access to specific entity types
+   - Custom permission validation
+
+**Configuration Options:**
+
+```jsx
+const associationConfig = {
+    // Required: Basic entity configuration
+    primaryEntity: {
+        id: "clients",                    // Unique identifier
+        label: "Clients",                 // Display name
+        displayKey: "name",               // Field to show in lists
+        fetchUrl: "/api/clients",         // API endpoint
+        searchFields: ["name", "email"],  // Fields to search
+        icon: "Users",                    // Lucide icon name
+        color: "#3b82f6"                  // Brand color
+    },
+    
+    secondaryEntity: {
+        id: "projects",
+        label: "Projects", 
+        displayKey: "title",
+        fetchUrl: "/api/projects",
+        searchFields: ["title", "description"],
+        icon: "FolderOpen",
+        color: "#10b981"
+    },
+
+    // Association configuration
+    association: {
+        fetchUrl: "/api/associations",     // Get existing associations
+        createUrl: "/api/associations",    // Create new associations
+        updateUrl: "/api/associations",    // Update associations (optional)
+        deleteUrl: "/api/associations",    // Delete associations
+        pivotTable: "client_project",      // Database table name
+        
+        // Additional pivot data
+        pivotFields: [
+            {
+                name: "role",
+                label: "Role",
+                type: "select",
+                options: [
+                    { value: "manager", label: "Manager" },
+                    { value: "contributor", label: "Contributor" }
+                ]
+            },
+            {
+                name: "start_date",
+                label: "Start Date",
+                type: "date"
+            }
+        ]
+    },
+
+    // UI customization
+    ui: {
+        layout: "split",                   // "split", "tabs", "cards"
+        theme: "default",                  // "default", "compact", "detailed"
+        showEntityCounts: true,            // Show association counts
+        showLastModified: true,            // Show modification timestamps
+        enableDragDrop: true,              // Enable drag-and-drop
+        confirmActions: true,              // Show confirmation dialogs
+        
+        // Custom labels and messages
+        labels: {
+            createButton: "Add Association",
+            deleteButton: "Remove",
+            searchPlaceholder: "Search entities...",
+            noResultsMessage: "No entities found",
+            loadingMessage: "Loading associations..."
+        }
+    },
+
+    // Validation rules
+    validation: {
+        preventDuplicates: true,           // Prevent duplicate associations
+        requirePivotData: false,           // Require additional pivot fields
+        customValidation: (primary, secondary, pivotData) => {
+            // Custom validation logic
+            return { valid: true, message: "" };
+        }
+    },
+
+    // Performance optimization
+    performance: {
+        enableVirtualization: true,        // For large datasets
+        pageSize: 50,                      // Pagination size
+        debounceMs: 300,                   // Search debounce
+        cacheResults: true                 // Cache API responses
+    }
+};
+```
+
+**API Integration:**
+
+The AssociationManager expects specific API response formats:
+
+```javascript
+// GET /api/clients (Primary Entity)
+{
+    "data": [
+        {
+            "id": 1,
+            "name": "Acme Corp",
+            "email": "contact@acme.com",
+            "created_at": "2023-01-01T00:00:00Z"
+        }
+    ],
+    "total": 150,
+    "page": 1,
+    "per_page": 50
+}
+
+// GET /api/associations (Existing Associations)
+{
+    "data": [
+        {
+            "id": 1,
+            "primary_id": 1,
+            "secondary_id": 5,
+            "pivot_data": {
+                "role": "manager",
+                "start_date": "2023-01-01"
+            },
+            "primary": {
+                "id": 1,
+                "name": "Acme Corp"
+            },
+            "secondary": {
+                "id": 5,
+                "title": "Website Redesign"
+            },
+            "created_at": "2023-01-01T00:00:00Z"
+        }
+    ]
+}
+
+// POST /api/associations (Create Association)
+{
+    "primary_id": 1,
+    "secondary_id": 5,
+    "pivot_data": {
+        "role": "manager",
+        "start_date": "2023-01-01"
+    }
+}
+
+// Response:
+{
+    "success": true,
+    "data": {
+        "id": 1,
+        "primary_id": 1,
+        "secondary_id": 5,
+        "created_at": "2023-01-01T00:00:00Z"
+    },
+    "message": "Association created successfully"
+}
+```
+
+**Event Handling:**
+
+```jsx
+<AssociationManager
+    config={associationConfig}
+    onAssociationChange={(event) => {
+        // event.type: 'created', 'updated', 'deleted'
+        // event.data: Association data
+        // event.entities: Affected entities
+        console.log('Association event:', event);
+    }}
+    onEntitySelect={(entity, type) => {
+        // Handle entity selection
+        console.log('Entity selected:', entity, type);
+    }}
+    onError={(error) => {
+        // Handle errors
+        console.error('Association error:', error);
+    }}
+/>
+```
+
+**Advanced Usage Examples:**
+
+1. **Client-Project Association with Roles**:
+```jsx
+// Managing client assignments to projects with specific roles
+<AssociationManager
+    config={{
+        primaryEntity: { id: "clients", label: "Clients", ... },
+        secondaryEntity: { id: "projects", label: "Projects", ... },
+        association: {
+            pivotFields: [
+                {
+                    name: "role",
+                    label: "Role in Project",
+                    type: "select",
+                    required: true,
+                    options: [
+                        { value: "sponsor", label: "Project Sponsor" },
+                        { value: "stakeholder", label: "Key Stakeholder" },
+                        { value: "user", label: "End User" }
+                    ]
+                }
+            ]
+        }
+    }}
+/>
+```
+
+2. **User-Permission Association**:
+```jsx
+// Managing user permissions with expiration dates
+<AssociationManager
+    config={{
+        primaryEntity: { id: "users", label: "Users", ... },
+        secondaryEntity: { id: "permissions", label: "Permissions", ... },
+        association: {
+            pivotFields: [
+                {
+                    name: "expires_at",
+                    label: "Expiration Date",
+                    type: "datetime",
+                    required: false
+                },
+                {
+                    name: "granted_by",
+                    label: "Granted By",
+                    type: "select",
+                    fetchUrl: "/api/users/managers"
+                }
+            ]
+        }
+    }}
+/>
+```
+
+### Business Card OCR Component
+
+#### BusinessCardOcr (Enhanced v5.11.1+)
+
+An advanced OCR (Optical Character Recognition) component specifically designed for scanning business cards and automatically extracting contact information. The component provides intelligent text recognition, client matching, and seamless contact management integration.
+
+```jsx
+<BusinessCardOcr
+    isOpen={showScanner}
+    onClose={() => setShowScanner(false)}
+    onContactSaved={(contact) => {
+        console.log('Contact saved:', contact);
+        // Handle the saved contact data
+    }}
+    fields={[
+        { id: 'name', label: 'Full Name', required: true },
+        { id: 'email', label: 'Email', type: 'email' },
+        { id: 'phone', label: 'Phone', type: 'tel' },
+        { id: 'company', label: 'Company' },
+        { id: 'position', label: 'Position' },
+        { id: 'address', label: 'Address', type: 'textarea' }
+    ]}
+    fetchConfig={{
+        ocrUrl: '/api/ocr/business-card',
+        saveUrl: '/api/contacts',
+        clientSearchUrl: '/api/clients/search',
+        duplicateCheckUrl: '/api/contacts/check-duplicate'
+    }}
+    settings={{
+        enableClientMatching: true,
+        enableDuplicateCheck: true,
+        autoSave: false,
+        imageQuality: 0.8,
+        supportedFormats: ['image/jpeg', 'image/png', 'image/webp']
+    }}
+/>
+```
+
+**Key Features:**
+
+1. **Advanced OCR Processing**:
+   - High-accuracy text extraction from business card images
+   - Intelligent field mapping and recognition
+   - Support for multiple languages and formats
+   - Automatic rotation and perspective correction
+
+2. **Smart Client Matching**:
+   - Automatic company name recognition
+   - Fuzzy matching against existing client database
+   - Confidence scoring for match suggestions
+   - Manual override and confirmation options
+
+3. **Duplicate Detection**:
+   - Email and phone number duplicate checking
+   - Visual comparison with existing contacts
+   - Merge or create new contact options
+   - Conflict resolution interface
+
+4. **Interactive Editing Interface**:
+   - Real-time field editing and validation
+   - Drag-and-drop image upload
+   - Live camera capture (mobile devices)
+   - Field confidence indicators
+
+5. **Contact Management Integration**:
+   - Direct save to contact database
+   - Custom field mapping and validation
+   - Bulk import capabilities
+   - Export to various formats
+
+**Configuration Options:**
+
+```jsx
+const businessCardConfig = {
+    // Field definitions for extracted data
+    fields: [
+        {
+            id: 'name',
+            label: 'Full Name',
+            type: 'text',
+            required: true,
+            validation: {
+                minLength: 2,
+                pattern: /^[a-zA-Z\s]+$/
+            },
+            ocrMapping: ['name', 'full_name', 'contact_name']
+        },
+        {
+            id: 'email',
+            label: 'Email Address', 
+            type: 'email',
+            required: false,
+            validation: {
+                pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+            },
+            ocrMapping: ['email', 'e_mail', 'email_address']
+        },
+        {
+            id: 'phone',
+            label: 'Phone Number',
+            type: 'tel',
+            required: false,
+            formatting: {
+                mask: '(000) 000-0000',
+                international: true
+            },
+            ocrMapping: ['phone', 'mobile', 'telephone', 'cell']
+        },
+        {
+            id: 'company',
+            label: 'Company Name',
+            type: 'text',
+            required: false,
+            clientMatching: true,  // Enable client matching for this field
+            ocrMapping: ['company', 'organization', 'business_name']
+        },
+        {
+            id: 'position',
+            label: 'Job Title',
+            type: 'text',
+            required: false,
+            ocrMapping: ['title', 'position', 'job_title', 'role']
+        },
+        {
+            id: 'address',
+            label: 'Address',
+            type: 'textarea',
+            required: false,
+            formatting: {
+                multiline: true,
+                rows: 3
+            },
+            ocrMapping: ['address', 'location', 'street_address']
+        },
+        {
+            id: 'website',
+            label: 'Website',
+            type: 'url',
+            required: false,
+            validation: {
+                pattern: /^https?:\/\/.+/
+            },
+            ocrMapping: ['website', 'url', 'web', 'site']
+        }
+    ],
+
+    // API endpoint configuration
+    fetchConfig: {
+        ocrUrl: '/api/ocr/business-card',           // OCR processing endpoint
+        saveUrl: '/api/contacts',                   // Contact save endpoint  
+        clientSearchUrl: '/api/clients/search',     // Client matching endpoint
+        duplicateCheckUrl: '/api/contacts/check',   // Duplicate check endpoint
+        uploadUrl: '/api/files/upload',             // Image upload endpoint
+        
+        // Request configuration
+        timeout: 30000,                             // 30 second timeout
+        retries: 3,                                 // Retry failed requests
+        headers: {
+            'Accept': 'application/json',
+            'X-Requested-With': 'XMLHttpRequest'
+        }
+    },
+
+    // Component behavior settings
+    settings: {
+        // OCR settings
+        imageQuality: 0.8,                          // Image compression quality
+        maxImageSize: 5242880,                      // 5MB max file size
+        supportedFormats: [                         // Accepted image formats
+            'image/jpeg',
+            'image/png', 
+            'image/webp',
+            'image/bmp'
+        ],
+        
+        // Processing options
+        enableClientMatching: true,                 // Enable company matching
+        enableDuplicateCheck: true,                 // Check for duplicates
+        autoSave: false,                           // Auto-save after OCR
+        requireConfirmation: true,                 // Confirm before saving
+        
+        // UI options
+        showConfidenceScores: true,                // Show OCR confidence
+        enableManualEdit: true,                    // Allow manual editing
+        showImagePreview: true,                    // Show uploaded image
+        enableCameraCapture: true,                 // Enable camera on mobile
+        
+        // Validation options
+        validateOnBlur: true,                      // Validate fields on blur
+        highlightErrors: true,                     // Highlight validation errors
+        showTooltips: true,                        // Show field tooltips
+        
+        // Performance options
+        debounceMs: 500,                           // Debounce for auto-save
+        cacheResults: true,                        // Cache OCR results
+        enablePreprocessing: true                  // Image preprocessing
+    },
+
+    // UI customization
+    ui: {
+        theme: 'default',                          // 'default', 'compact', 'minimal'
+        layout: 'modal',                           // 'modal', 'inline', 'drawer'
+        size: 'large',                             // 'small', 'medium', 'large'
+        
+        // Labels and messages
+        labels: {
+            uploadButton: 'Upload Business Card',
+            scanButton: 'Scan with Camera',
+            saveButton: 'Save Contact',
+            cancelButton: 'Cancel',
+            editButton: 'Edit Information',
+            processButton: 'Process Image'
+        },
+        
+        messages: {
+            uploadPrompt: 'Drop an image here or click to upload',
+            processing: 'Processing business card...',
+            ocrSuccess: 'Text extracted successfully',
+            ocrError: 'Failed to process image',
+            saveSuccess: 'Contact saved successfully',
+            duplicateFound: 'Duplicate contact detected'
+        },
+        
+        // Style customization
+        styles: {
+            primaryColor: '#3b82f6',
+            successColor: '#10b981',
+            errorColor: '#ef4444',
+            borderRadius: '8px',
+            boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)'
+        }
+    }
+};
+```
+
+**API Integration:**
+
+The BusinessCardOcr component expects specific API response formats:
+
+```javascript
+// POST /api/ocr/business-card (OCR Processing)
+// Request: FormData with image file
+{
+    "image": File
+}
+
+// Response:
+{
+    "success": true,
+    "data": {
+        "extracted_text": "John Smith\nSenior Developer\nAcme Corp\nj.smith@acme.com\n(555) 123-4567",
+        "fields": {
+            "name": {
+                "value": "John Smith",
+                "confidence": 0.95,
+                "position": { "x": 100, "y": 50, "width": 200, "height": 30 }
+            },
+            "email": {
+                "value": "j.smith@acme.com", 
+                "confidence": 0.92,
+                "position": { "x": 100, "y": 120, "width": 250, "height": 25 }
+            },
+            "company": {
+                "value": "Acme Corp",
+                "confidence": 0.88,
+                "position": { "x": 100, "y": 80, "width": 150, "height": 25 }
+            }
+        },
+        "processing_time": 2.3,
+        "image_url": "/storage/uploads/card_123.jpg"
+    }
+}
+
+// GET /api/clients/search (Client Matching)
+{
+    "query": "Acme Corp"
+}
+
+// Response:
+{
+    "data": [
+        {
+            "id": 5,
+            "name": "Acme Corporation",
+            "match_score": 0.85,
+            "address": "123 Business St",
+            "phone": "(555) 987-6543",
+            "website": "https://acme.com"
+        }
+    ]
+}
+
+// POST /api/contacts/check (Duplicate Check)
+{
+    "email": "j.smith@acme.com",
+    "phone": "(555) 123-4567"
+}
+
+// Response:
+{
+    "duplicates": [
+        {
+            "id": 10,
+            "name": "John Smith",
+            "email": "j.smith@acme.com",
+            "match_type": "email",
+            "match_score": 1.0,
+            "created_at": "2023-01-01T00:00:00Z"
+        }
+    ]
+}
+
+// POST /api/contacts (Save Contact)
+{
+    "name": "John Smith",
+    "email": "j.smith@acme.com",
+    "phone": "(555) 123-4567",
+    "company": "Acme Corp",
+    "position": "Senior Developer",
+    "client_id": 5,
+    "source": "business_card_ocr",
+    "confidence_scores": {
+        "name": 0.95,
+        "email": 0.92,
+        "company": 0.88
+    }
+}
+
+// Response:
+{
+    "success": true,
+    "data": {
+        "id": 15,
+        "name": "John Smith",
+        "created_at": "2023-01-01T00:00:00Z"
+    },
+    "message": "Contact created successfully"
+}
+```
+
+**Event Handling:**
+
+```jsx
+<BusinessCardOcr
+    isOpen={showScanner}
+    onClose={() => setShowScanner(false)}
+    onContactSaved={(contact) => {
+        // Handle successful contact save
+        console.log('New contact saved:', contact);
+        
+        // Optional: Update parent component state
+        setContacts(prev => [...prev, contact]);
+        
+        // Optional: Show success notification
+        toast.success(`Contact ${contact.name} saved successfully`);
+    }}
+    onOcrComplete={(extractedData) => {
+        // Handle OCR completion
+        console.log('OCR extraction completed:', extractedData);
+        
+        // Optional: Custom processing of extracted data
+        if (extractedData.confidence < 0.7) {
+            toast.warning('Low confidence OCR results. Please review carefully.');
+        }
+    }}
+    onClientMatch={(matches) => {
+        // Handle client matching results
+        console.log('Client matches found:', matches);
+        
+        // Optional: Auto-select high confidence matches
+        if (matches.length === 1 && matches[0].match_score > 0.9) {
+            // Auto-select the best match
+            return matches[0];
+        }
+    }}
+    onDuplicateDetected={(duplicates) => {
+        // Handle duplicate detection
+        console.log('Duplicate contacts found:', duplicates);
+        
+        // Optional: Custom duplicate handling logic
+        return new Promise((resolve) => {
+            // Show custom duplicate resolution UI
+            showDuplicateDialog(duplicates, resolve);
+        });
+    }}
+    onError={(error) => {
+        // Handle errors
+        console.error('OCR error:', error);
+        
+        // Optional: Custom error handling
+        if (error.type === 'network') {
+            toast.error('Network error. Please check your connection.');
+        } else if (error.type === 'validation') {
+            toast.error('Please correct the highlighted fields.');
+        }
+    }}
+/>
+```
+
+**Advanced Usage Examples:**
+
+1. **Integration with Existing Contact Form**:
+```jsx
+const ContactForm = () => {
+    const [showOcr, setShowOcr] = useState(false);
+    const [formData, setFormData] = useState({});
+
+    return (
+        <div>
+            <Form data={formData} onChange={setFormData}>
+                {/* Regular form fields */}
+            </Form>
+            
+            <button onClick={() => setShowOcr(true)}>
+                Scan Business Card
+            </button>
+            
+            <BusinessCardOcr
+                isOpen={showOcr}
+                onClose={() => setShowOcr(false)}
+                onContactSaved={(contact) => {
+                    // Pre-fill form with OCR data
+                    setFormData(contact);
+                    setShowOcr(false);
+                }}
+            />
+        </div>
+    );
+};
+```
+
+2. **Bulk Business Card Processing**:
+```jsx
+const BulkCardProcessor = () => {
+    const [queue, setQueue] = useState([]);
+    
+    return (
+        <BusinessCardOcr
+            settings={{
+                autoSave: true,
+                enableBulkMode: true
+            }}
+            onContactSaved={(contact) => {
+                setQueue(prev => [...prev, contact]);
+            }}
+            onBulkComplete={(contacts) => {
+                console.log(`Processed ${contacts.length} business cards`);
+            }}
+        />
+    );
+};
+```
+
 ### Utility Components
 
 #### CustomFetch
@@ -1309,9 +2069,9 @@ Response:
 
 ### Report Builder Component
 
-#### GenericReport
+#### GenericReport (Enhanced v5.10.11+)
 
-A powerful report building component that allows users to create custom reports by selecting tables, columns, and configuring joins, filters, and sorting.
+A powerful and enhanced report building component that provides an intuitive wizard-based interface for creating custom reports. The component has been significantly improved with new features and better user experience.
 
 ```jsx
 <GenericReport
@@ -1322,19 +2082,108 @@ A powerful report building component that allows users to create custom reports
         executeUrl: '/ajax/reportBuilder/execute',
         suggestedJoinsUrl: '/ajax/reportBuilder/getSuggestedJoins',
     }}
+    userProfile={userProfile}
+    businessTemplates={businessTemplates} // Optional pre-built templates
 />
 ```
 
-The GenericReport component provides these features:
+**Major Enhancements:**
+
+-   **5-Step Wizard Interface**: Guided workflow with visual progress indicators
+-   **Business Templates**: Pre-built report templates for common business scenarios
+-   **Calculated Fields**: Create custom formulas and calculations within reports
+-   **Smart Column Selection**: Automatic suggestions based on table relationships
+-   **Enhanced Filtering**: Advanced filter options with AND/OR logic and grouping
+-   **Live Preview**: Real-time preview of report data as you build
+-   **Intelligent Currency Formatting**: Automatic detection and formatting of monetary fields
+-   **Expandable Field Summary**: View selected fields in a collapsible overview
+-   **Template Management**: Save, load, and share report templates
+-   **Multiple Export Formats**: Export to Excel, CSV, PDF with formatting options
+
+**New Features in Recent Updates:**
+
+1. **Calculated Fields (v5.10.12+)**:
+   ```jsx
+   // Users can create custom calculated fields
+   {
+       id: 'profit_margin',
+       displayName: 'Profit Margin %',
+       formula: 'ROUND(((revenue - cost) / revenue) * 100, 2)',
+       type: 'decimal'
+   }
+   ```
+
+2. **Business Templates (v5.11.0+)**:
+   ```jsx
+   // Pre-built templates for common scenarios
+   const businessTemplates = [
+       {
+           id: 'utilization_planning',
+           name: 'Utilization Planning',
+           description: 'Weekly resource allocation and laydown utilization',
+           icon: 'Calendar',
+           mainTable: 'leads',
+           defaultColumns: [...],
+           calculatedFields: [...]
+       }
+   ];
+   ```
+
+3. **Smart Currency Detection**:
+   - Automatically formats fields containing 'value', 'price', 'cost', 'amount', etc.
+   - Supports Australian Dollar (AUD) formatting by default
+   - Configurable currency formatting options
+
+4. **Enhanced UI/UX**:
+   - Lucide React icons throughout for consistency
+   - Larger calculated field display for better visibility
+   - Expandable selected fields summary
+   - Step-by-step guidance with tooltips and help text
+
+**The 5-Step Wizard Process:**
+
+1. **Select Data Source**: Choose main table and review business templates
+2. **Choose Columns**: Select specific data fields with drag-and-drop reordering
+3. **Add Relationships**: Connect related tables with automatic join suggestions
+4. **Apply Filters**: Set conditions and date ranges with advanced logic
+5. **Generate & Export**: Preview results and export in multiple formats
+
+**API Integration:**
+
+The component expects these endpoint responses:
+
+```javascript
+// Tables endpoint
+{
+    "tables": [
+        {
+            "id": "clients",
+            "label": "Clients",
+            "description": "Customer information"
+        }
+    ]
+}
+
+// Columns endpoint
+{
+    "columns": [
+        {
+            "name": "id",
+            "type": "integer",
+            "nullable": false,
+            "key": "primary"
+        }
+    ]
+}
 
--   **Table Selection**: Choose a main table for the report
--   **Column Selection**: Select columns to include in the report
--   **Table Joins**: Add related tables with automatic relationship detection
--   **Filtering**: Apply filters to the report data
--   **Sorting**: Sort the report results
--   **Report Preview**: View a preview of the report data
--   **Save/Load Reports**: Save reports for future use and load saved reports
--   **Export**: Export reports in various formats
+// Execute endpoint
+{
+    "success": true,
+    "data": [...],
+    "total": 150,
+    "query": "SELECT ... FROM ..."
+}
+```
 
 ### Sketch Field Component
 
@@ -1501,6 +2350,359 @@ We welcome contributions! Please follow these steps:
 
 [MIT License](LICENSE)
 
+### Quote Management Components
+
+#### GenericQuote (Enhanced with Proposal System v5.12.0+)
+
+The GenericQuote component provides comprehensive quote management with integrated proposal generation capabilities. It supports both traditional quote display and full proposal creation with cover pages, table of contents, and customizable sections.
+
+```jsx
+<GenericQuote
+    config={{
+        // Basic quote configuration
+        data: quoteData,
+        currency: "AUD",
+        companyLogo: "/path/to/logo.png",
+        
+        // Standard features
+        showLineItems: true,
+        allowEditing: true,
+        showNotes: true,
+        
+        // Enhanced proposal features (v5.12.0+)
+        proposalMode: {
+            enabled: true,
+            templateId: 1,
+            brandingProfileId: 2,
+            customSections: [
+                {
+                    type: 'overview',
+                    title: 'Project Overview',
+                    content: '<h1>Executive Summary</h1><p>This proposal outlines...</p>'
+                },
+                {
+                    type: 'terms_conditions',
+                    title: 'Terms & Conditions',
+                    content: '<h3>Payment Terms</h3><p>Net 30 days...</p>'
+                }
+            ]
+        }
+    }}
+    userProfile={userProfile}
+    onQuoteSave={(quoteData) => handleQuoteSave(quoteData)}
+    onProposalGenerate={(proposalData) => handleProposalGeneration(proposalData)}
+/>
+```
+
+**New Proposal Features:**
+
+1. **Proposal Mode Toggle**:
+   - Seamlessly switch between quote view and proposal generation mode
+   - Maintains full backward compatibility with existing quote functionality
+   - Context-aware interface that adapts based on proposal configuration
+
+2. **Template Management Integration**:
+   - Select from pre-configured proposal templates
+   - Template preview with variable substitution
+   - Custom section creation and ordering
+   - Dynamic content population from quote data
+
+3. **Branding Profile Support**:
+   - Company logo and branding integration
+   - Custom color schemes and styling
+   - Professional cover page generation
+   - Consistent brand presentation
+
+4. **Advanced Section Management**:
+   - **Cover Page**: Company branding with proposal title and customer details
+   - **Table of Contents**: Auto-generated from all proposal sections
+   - **Overview**: Executive summary with custom headers (H1, H2, H3) and content
+   - **Quote Items**: Pricing table following original quote structure
+   - **Terms & Conditions**: Static legal terms (rarely changes)
+   - **Payment Terms**: Dynamic payment schedules and due dates
+   - **Review Log**: Version history and change tracking
+   - **Agreement & Signatures**: Static signature section for approvals
+
+5. **Dynamic Content System**:
+   - Variable replacement throughout all sections
+   - Real-time preview of populated content
+   - Support for both static and dynamic sections
+   - Custom variable definitions per template
+
+**Configuration Options:**
+
+```jsx
+const proposalConfig = {
+    // Enable proposal features
+    enabled: true,
+    
+    // Template selection
+    templateId: 1,                          // Selected proposal template
+    allowTemplateChange: true,              // Allow template switching
+    
+    // Branding configuration
+    brandingProfileId: 2,                   // Selected branding profile
+    allowBrandingChange: true,              // Allow branding changes
+    
+    // Section customization
+    customSections: [
+        {
+            type: 'overview',
+            title: 'Project Overview',
+            content: '<h1>Executive Summary</h1><p>Custom content...</p>',
+            variables: {
+                'project_scope': 'Website development and maintenance',
+                'timeline': '8-12 weeks'
+            }
+        }
+    ],
+    
+    // Generation settings
+    autoGenerateTOC: true,                  // Auto-generate table of contents
+    includePageNumbers: true,               // Add page numbers to PDF
+    watermark: false,                       // Add watermark to pages
+    
+    // PDF export options
+    paperSize: 'A4',                        // Paper size for PDF generation
+    orientation: 'portrait',                // Page orientation
+    margins: '40px',                        // Page margins
+    
+    // UI customization
+    showPreview: true,                      // Show live preview panel
+    previewMode: 'split',                   // 'split', 'modal', 'tabs'
+    enableSectionReorder: true,             // Allow section drag-and-drop
+    showVariableHelper: true,               // Show available variables
+};
+```
+
+**Available Variables for Dynamic Content:**
+
+The proposal system supports these built-in variables that are automatically populated from quote and customer data:
+
+```javascript
+// Customer Information
+{{customer_name}}           // Customer company name
+{{customer_address}}        // Customer full address
+{{customer_contact}}        // Primary contact name
+{{customer_email}}          // Primary contact email
+{{customer_phone}}          // Primary contact phone
+
+// Quote Information
+{{quote_number}}            // Quote/proposal number
+{{quote_date}}              // Quote creation date
+{{quote_valid_until}}       // Quote expiration date
+{{total_amount}}            // Total quote amount (formatted)
+{{total_ex_gst}}           // Total excluding GST
+{{total_gst}}              // GST amount
+{{currency}}               // Currency symbol/code
+
+// Company Information
+{{company_name}}            // Your company name
+{{company_address}}         // Your company address
+{{company_phone}}           // Your company phone
+{{company_email}}           // Your company email
+{{company_website}}         // Your company website
+{{company_abn}}            // Australian Business Number
+
+// Project Information
+{{project_manager}}         // Assigned project manager
+{{project_timeline}}        // Estimated timeline
+{{project_scope}}          // Project scope description
+
+// Date Variables
+{{current_date}}           // Current date
+{{due_date}}              // Payment due date
+{{start_date}}            // Project start date
+
+// Item-Specific Variables
+{{items_onceoff}}         // One-time purchase items table
+{{items_monthly}}         // Monthly subscription items table
+{{items_yearly}}          // Yearly subscription items table
+{{line_items_total}}      // Total number of line items
+```
+
+**Integration with visns-packages Backend:**
+
+The GenericQuote component seamlessly integrates with the visns-packages proposal system:
+
+```jsx
+// Backend integration endpoints
+const proposalEndpoints = {
+    // Template management
+    templates: '/ajax/proposal-templates',
+    templatePreview: '/ajax/proposal-templates/{id}/preview',
+    
+    // Branding profiles
+    brandingProfiles: '/ajax/branding-profiles',
+    brandingCSS: '/ajax/branding-profiles/{id}/css',
+    
+    // PDF generation
+    generatePDF: '/ajax/pdf/generate-proposal',
+    previewHTML: '/ajax/pdf/preview-proposal',
+    
+    // Variable helpers
+    availableVariables: '/ajax/proposal-templates/variables/available'
+};
+```
+
+**Event Handling:**
+
+```jsx
+<GenericQuote
+    config={quoteConfig}
+    // Quote events (existing)
+    onQuoteSave={(data) => console.log('Quote saved:', data)}
+    onLineItemChange={(items) => console.log('Line items updated:', items)}
+    
+    // New proposal events
+    onProposalGenerate={(proposalData) => {
+        console.log('Proposal generated:', proposalData);
+        // Handle PDF generation or preview
+    }}
+    onTemplateChange={(templateId) => {
+        console.log('Template changed to:', templateId);
+        // Update template-specific settings
+    }}
+    onBrandingChange={(brandingId) => {
+        console.log('Branding changed to:', brandingId);
+        // Update branding-specific styling
+    }}
+    onSectionUpdate={(sections) => {
+        console.log('Sections updated:', sections);
+        // Handle custom section changes
+    }}
+    onVariableChange={(variables) => {
+        console.log('Variables updated:', variables);
+        // Handle variable substitution updates
+    }}
+/>
+```
+
+**Backward Compatibility:**
+
+All existing GenericQuote functionality remains unchanged:
+- Standard quote display and editing
+- Line item management
+- Notes and attachments
+- Export capabilities
+- Custom actions and workflows
+
+Proposal features are **opt-in** and activated only when `proposalConfig.enabled: true` is set.
+
+**Advanced Usage Example:**
+
+```jsx
+import React, { useState } from 'react';
+import { GenericQuote } from '@visns-studio/visns-components';
+
+const QuoteProposalManager = () => {
+    const [quoteData, setQuoteData] = useState({
+        id: 1,
+        number: 'Q-2024-001',
+        customer: {
+            name: 'Acme Corporation',
+            address: '123 Business St, Sydney NSW 2000',
+            contact: 'John Smith',
+            email: 'john@acme.com'
+        },
+        items: [
+            {
+                description: 'Website Development',
+                quantity: 1,
+                rate: 5000,
+                total: 5000,
+                type: 'onceoff'
+            },
+            {
+                description: 'Monthly Hosting',
+                quantity: 1,
+                rate: 99,
+                total: 99,
+                type: 'monthly'
+            }
+        ],
+        total: 5099
+    });
+
+    const [proposalMode, setProposalMode] = useState(false);
+
+    const proposalConfig = {
+        enabled: true,
+        templateId: 1,
+        brandingProfileId: 1,
+        customSections: [
+            {
+                type: 'overview',
+                title: 'Project Overview',
+                content: `
+                    <h1>Executive Summary</h1>
+                    <p>This proposal outlines our recommended solution for {{customer_name}}.</p>
+                    
+                    <h2>Project Scope</h2>
+                    <p>We will develop a modern, responsive website that meets your business requirements.</p>
+                    
+                    <h3>Key Deliverables</h3>
+                    <ul>
+                        <li>Custom website design and development</li>
+                        <li>Content management system</li>
+                        <li>Mobile-responsive design</li>
+                        <li>SEO optimization</li>
+                    </ul>
+                `
+            }
+        ],
+        autoGenerateTOC: true,
+        showPreview: true,
+        previewMode: 'split'
+    };
+
+    return (
+        <div className="quote-proposal-manager">
+            <div className="mode-toggle">
+                <button 
+                    onClick={() => setProposalMode(false)}
+                    className={!proposalMode ? 'active' : ''}
+                >
+                    Quote View
+                </button>
+                <button 
+                    onClick={() => setProposalMode(true)}
+                    className={proposalMode ? 'active' : ''}
+                >
+                    Proposal Builder
+                </button>
+            </div>
+
+            <GenericQuote
+                config={{
+                    data: quoteData,
+                    currency: "AUD",
+                    showLineItems: true,
+                    allowEditing: !proposalMode,
+                    
+                    // Enable proposal features based on mode
+                    proposalMode: proposalMode ? proposalConfig : { enabled: false }
+                }}
+                userProfile={userProfile}
+                onQuoteSave={(data) => {
+                    setQuoteData(data);
+                    console.log('Quote updated:', data);
+                }}
+                onProposalGenerate={(proposalData) => {
+                    // Generate PDF or handle proposal data
+                    console.log('Generating proposal PDF:', proposalData);
+                    
+                    // Example: Download PDF
+                    window.open(`/ajax/pdf/generate-proposal?quote_id=${quoteData.id}`, '_blank');
+                }}
+            />
+        </div>
+    );
+};
+
+export default QuoteProposalManager;
+```
+
 ## Modal Actions in Components
 
 ### Using Modal Actions in GenericQuote Component