@visns-studio/visns-components 5.11.3 → 5.11.5

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:
 
--   **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
+```javascript
+// Tables endpoint
+{
+    "tables": [
+        {
+            "id": "clients",
+            "label": "Clients",
+            "description": "Customer information"
+        }
+    ]
+}
+
+// Columns endpoint
+{
+    "columns": [
+        {
+            "name": "id",
+            "type": "integer",
+            "nullable": false,
+            "key": "primary"
+        }
+    ]
+}
+
+// Execute endpoint
+{
+    "success": true,
+    "data": [...],
+    "total": 150,
+    "query": "SELECT ... FROM ..."
+}
+```
 
 ### Sketch Field Component
 
@@ -1650,6 +2499,61 @@ Modal components support vertical alignment configuration with the `verticalAlig
 
 The ReactDataGrid's `defaultGroupBy` prop enables internal grouping functionality that creates collapsible group headers within the table structure. It does NOT create any external UI elements that need relocation, as all grouping controls are internal to the table component.
 
+### Navigation Component Icon Visibility Issues
+
+#### Browser Rendering Optimization Fix
+
+**Problem:** Navigation action icons (specifically anchor/Link elements) would disappear during page scroll in production environments. The issue only affected anchor tags while button elements remained visible. Notably, the problem disappeared when browser dev tools were open, indicating a browser rendering optimization conflict.
+
+**Root Cause:** Firefox and other browsers apply aggressive rendering optimizations that can incorrectly cull elements from the paint tree. The combination of CSS `contain: layout` property with sticky positioning was causing anchor elements to be optimized out of view during scroll events.
+
+**Solution Applied:**
+
+1. **Removed problematic containment properties:**
+   - Removed `contain: layout` from `.content-header` and action elements
+   - This property was causing layout optimization conflicts
+
+2. **Enhanced compositor layer creation:**
+   - Changed `transform: translateZ(0)` to `transform: translateZ(0) translateX(0) translateY(0)`
+   - Added `isolation: isolate` to force elements onto their own render layers
+   - Added `backface-visibility: hidden` to prevent rendering glitches
+
+3. **Improved z-index stacking:**
+   - Elevated z-index values from 100-103 range to 1000-1003 range
+   - Ensures action icons stay above sticky header's stacking context
+
+**Files Modified:**
+- `src/components/crm/styles/Navigation.module.scss` (content-header and action styling)
+- Enhanced both regular and alternate theme action containers
+
+#### Navigation Component Debug Mode
+
+The Navigation component now includes optional debugging capabilities to help diagnose rendering issues:
+
+**Enable Debug Mode:**
+```jsx
+<Navigation debugIcons={true} {...otherProps} />
+```
+
+**Debug Features:**
+- **Visual indicators:** Red borders around anchor elements with 'A' labels, blue borders around buttons with 'B' labels
+- **Console logging:** Detailed scroll event logs showing element positions, visibility, z-index, transforms, and containment properties
+- **Real-time monitoring:** Tracks icon visibility changes during scroll events
+
+**Debug CSS Classes:**
+The component includes `.debug-icons` styles that can be applied for visual debugging:
+```scss
+.debug-icons {
+    a, button {
+        border: 2px solid red !important;
+        background: rgba(255, 0, 0, 0.1) !important;
+        // Additional debug styling...
+    }
+}
+```
+
+This fix ensures navigation icons remain visible during scroll across all browser environments and rendering contexts.
+
 ## Support
 
 For support, please contact the VISNS Studio team or open an issue on GitHub.