@visns-studio/visns-components 5.15.20 → 5.15.22

package/README.md

@@ -69,7 +69,7 @@ VISNS Components is a React-based UI component library that provides a set of re
 
 ### Utility Components
 
--   **Fetch** - Axios-based data fetching with error handling
+-   **Fetch** - Advanced data fetching with intelligent caching, error handling, and TanStack Query integration
 -   **Download** - File download functionality
 -   **Loader** - Loading indicators
 -   **Notification** - Toast notifications
@@ -2489,18 +2489,20 @@ const BulkCardProcessor = () => {
 
 ### Utility Components
 
-#### CustomFetch
+#### CustomFetch (Fetch.jsx)
 
-Data fetching utility with error handling and payload size validation.
+Advanced data fetching utility with intelligent caching, error handling, and payload validation powered by TanStack Query (v5.15.21+).
 
 ```jsx
-// Using async/await
+import CustomFetch from '@visns-studio/visns-components';
+
+// Basic usage - async/await
 const result = await CustomFetch('/api/data', 'GET', { param1: 'value1' });
 
 // Using callbacks
 CustomFetch(
     '/api/data',
-    'GET',
+    'POST',
     { param1: 'value1' },
     (result) => {
         // Success callback
@@ -2511,16 +2513,71 @@ CustomFetch(
         console.error(error);
     }
 );
+
+// Manual cache management
+CustomFetch.invalidateCache('/api/data');  // Invalidate specific pattern
+CustomFetch.clearCache();                  // Clear all cache
 ```
 
-The CustomFetch component includes these features:
+**Core Features:**
 
--   **Payload Size Validation**: Automatically checks if the request payload exceeds the maximum allowed size (default: 4.5MB, configurable via `VITE_MAX_PAYLOAD_SIZE_MB` environment variable)
--   **Toast Notifications**: Displays error messages using toast notifications
+-   **Intelligent Caching**: Selective caching with TanStack Query for optimal performance
+-   **Payload Size Validation**: Automatically validates request size (default: 4.5MB, configurable via `VITE_MAX_PAYLOAD_SIZE_MB`)
+-   **Toast Notifications**: Error messages displayed using react-toastify
 -   **Promise Tracking**: Integrates with react-promise-tracker for loading indicators
 -   **HTML Error Parsing**: Properly renders HTML content in error messages
--   **CSRF Protection**: Redirects to login page on CSRF token mismatch
--   **Authentication Handling**: Silently handles unauthenticated errors without showing toast notifications
+-   **CSRF Protection**: Automatic token handling and redirect on mismatch
+-   **Authentication Handling**: Silent handling of unauthenticated errors
+
+**Caching Strategy (v5.15.21+):**
+
+The Fetch component implements an intelligent caching strategy designed to balance performance with data freshness:
+
+-   **GET Requests**: NOT cached by default to ensure data freshness
+-   **Selective POST Caching**: Only specific safe endpoints are cached:
+    -   `/dropdown` - Reference data (10 min stale time) - Industries, facilities, user lists
+    -   `/table` - Table queries (1 min stale time) - Grid data with stable results
+    -   `/availabilities` - Report availability (2 min stale time) - Report metadata
+    -   `/reports/` - Report data (2 min stale time) - Generated report results
+    -   `/dashboard/` - Dashboard metrics (5 min stale time) - Aggregated metrics
+    -   Wharf usage endpoints (30 sec stale time) - Real-time usage data
+
+-   **Auto-invalidation**: Mutations (POST/PUT/PATCH/DELETE) automatically invalidate related caches:
+    -   Lead mutations → invalidate lead tables and dashboards
+    -   Client mutations → invalidate client dropdowns and tables  
+    -   Agreement mutations → invalidate agreement tables and reports
+    -   Facility mutations → invalidate availability and report caches
+    -   Any data mutation → invalidate related report caches
+
+-   **Cache Configuration**:
+    -   **Cache Time**: 10 minutes - data stays in memory
+    -   **Stale Time**: Varies by endpoint type (30 seconds to 10 minutes)
+    -   **Retry Policy**: Conservative 1 retry on failure
+    -   **Window Focus**: No automatic refetch on focus
+    -   **Network Reconnect**: Automatic refetch on reconnection
+
+**Advanced Cache Control:**
+
+```jsx
+// Invalidate specific cache patterns
+CustomFetch.invalidateCache('/clients/dropdown');  // String pattern
+CustomFetch.invalidateCache(['clients', 'table']); // Array key
+
+// Clear entire cache
+CustomFetch.clearCache();
+
+// Access QueryClient for advanced operations
+const queryClient = CustomFetch.getQueryClient();
+queryClient.invalidateQueries({ queryKey: ['specific', 'key'] });
+```
+
+**Implementation Details:**
+
+-   **Singleton QueryClient**: Single instance shared across entire application
+-   **Cache Key Generation**: Consistent keys based on URL, method, and parameters
+-   **Smart Invalidation**: Related caches automatically cleared on mutations
+-   **Error Preservation**: Original error handling callbacks maintained
+-   **Backward Compatibility**: All existing CustomFetch usage continues to work unchanged
 
 #### CameraPlacement
 Interactive camera placement and visualization tool for security system design. Features a comprehensive Verkada camera database, FOV triangle visualization, and professional export capabilities with enhanced UI consistency.

package/package.json

@@ -94,7 +94,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "5.15.20",
+    "version": "5.15.22",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/Fetch.jsx

@@ -55,8 +55,8 @@ const generateCacheKey = (url, method, formData) => {
 const shouldCache = (method, url) => {
     const normalizedMethod = method.toUpperCase();
     
-    // Always cache GET requests
-    if (normalizedMethod === 'GET') return true;
+    // Don't cache GET requests
+    if (normalizedMethod === 'GET') return false;
     
     // Cache specific safe POST endpoints that return reference data
     const cacheableEndpoints = [
@@ -75,7 +75,7 @@ const shouldCache = (method, url) => {
 
 // Dynamic stale time based on endpoint type
 const getStaleTime = (url) => {
-    if (url.includes('/dropdown')) return 10 * 60 * 1000; // 10 minutes for dropdown data
+    if (url.includes('/dropdown')) return 1 * 60 * 1000; // 1 minute for dropdown data
     if (url.includes('/dashboard/')) return 5 * 60 * 1000; // 5 minutes for dashboard data
     if (url.includes('/availabilities') || url.includes('/reports/')) return 2 * 60 * 1000; // 2 minutes for reports
     if (url.includes('/table')) return 1 * 60 * 1000; // 1 minute for table data

package/src/components/ImportWizardModal.jsx

@@ -0,0 +1,627 @@
+import React, { useState, useEffect } from 'react';
+import { 
+    X,
+    Upload,
+    ArrowRight,
+    ArrowLeft,
+    CheckCircle,
+    AlertTriangle,
+    FileText,
+    Eye,
+    Download,
+    RefreshCw,
+    Zap
+} from 'lucide-react';
+import { toast } from 'react-toastify';
+import { useDropzone } from 'react-dropzone';
+import StandardModal from './generic/StandardModal';
+import Select from './Select';
+import CustomFetch from './Fetch';
+import styles from './styles/ImportWizardModal.module.scss';
+
+const ImportWizardModal = ({
+    isOpen,
+    onClose,
+    modelConfig = [],
+    importUrl,
+    onComplete,
+    title = "Import Data",
+    targetModel,
+    parentId = null,
+    relationKey = null
+}) => {
+    const [currentStep, setCurrentStep] = useState(1);
+    const [loading, setLoading] = useState(false);
+    const [uploadedFile, setUploadedFile] = useState(null);
+    const [fileData, setFileData] = useState(null);
+    const [columnMapping, setColumnMapping] = useState({});
+    const [previewData, setPreviewData] = useState([]);
+    const [validationSummary, setValidationSummary] = useState(null);
+    const [importResults, setImportResults] = useState(null);
+
+    const steps = [
+        {
+            id: 1,
+            title: 'Upload File',
+            description: 'Upload your CSV or Excel file',
+            icon: <Upload size={20} />
+        },
+        {
+            id: 2,
+            title: 'Map Columns',
+            description: 'Map file columns to data fields',
+            icon: <ArrowRight size={20} />
+        },
+        {
+            id: 3,
+            title: 'Preview Data',
+            description: 'Review mapped data before import',
+            icon: <Eye size={20} />
+        },
+        {
+            id: 4,
+            title: 'Import',
+            description: 'Import data to system',
+            icon: <Zap size={20} />
+        }
+    ];
+
+    // Reset state when modal opens/closes
+    useEffect(() => {
+        if (isOpen) {
+            resetWizard();
+        }
+    }, [isOpen]);
+
+    const resetWizard = () => {
+        setCurrentStep(1);
+        setUploadedFile(null);
+        setFileData(null);
+        setColumnMapping({});
+        setPreviewData([]);
+        setValidationSummary(null);
+        setImportResults(null);
+    };
+
+    // File upload dropzone configuration
+    const { getRootProps, getInputProps, isDragActive } = useDropzone({
+        accept: {
+            'text/csv': ['.csv'],
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['.xlsx'],
+            'application/vnd.ms-excel': ['.xls']
+        },
+        maxFiles: 1,
+        maxSize: 10 * 1024 * 1024, // 10MB
+        onDrop: handleFileUpload,
+        disabled: loading
+    });
+
+    async function handleFileUpload(acceptedFiles) {
+        if (acceptedFiles.length === 0) return;
+        
+        const file = acceptedFiles[0];
+        setUploadedFile(file);
+        setLoading(true);
+
+        try {
+            const formData = new FormData();
+            formData.append('file', file);
+
+            const response = await CustomFetch('/ajax/import/parse-file', {
+                method: 'POST',
+                body: formData,
+            });
+
+            if (response.success) {
+                setFileData(response.data);
+                
+                // Auto-suggest column mappings
+                await getSuggestedMappings(response.data.headers);
+                
+                setCurrentStep(2);
+                toast.success(`File parsed successfully! Found ${response.data.total_rows} rows.`);
+            } else {
+                toast.error(response.message || 'Failed to parse file');
+            }
+        } catch (error) {
+            console.error('File upload error:', error);
+            toast.error('Error uploading file');
+        } finally {
+            setLoading(false);
+        }
+    }
+
+    async function getSuggestedMappings(headers) {
+        try {
+            const response = await CustomFetch('/ajax/import/column-suggestions', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    headers: headers,
+                    model_fields: modelConfig
+                })
+            });
+
+            if (response.success) {
+                setColumnMapping(response.suggestions);
+            }
+        } catch (error) {
+            console.error('Error getting suggestions:', error);
+        }
+    }
+
+    const handleMappingChange = (fileColumn, modelField) => {
+        setColumnMapping(prev => ({
+            ...prev,
+            [fileColumn]: modelField
+        }));
+    };
+
+    const getRequiredFields = () => {
+        return modelConfig.filter(field => field.required).map(field => field.id);
+    };
+
+    const getMappedFields = () => {
+        return Object.values(columnMapping).filter(field => field);
+    };
+
+    const getUnmappedRequiredFields = () => {
+        const requiredFields = getRequiredFields();
+        const mappedFields = getMappedFields();
+        return requiredFields.filter(field => !mappedFields.includes(field));
+    };
+
+    const canProceedToPreview = () => {
+        return getUnmappedRequiredFields().length === 0;
+    };
+
+    async function handlePreviewMapping() {
+        if (!canProceedToPreview()) {
+            toast.error('Please map all required fields before proceeding');
+            return;
+        }
+
+        setLoading(true);
+        
+        try {
+            const formData = new FormData();
+            formData.append('file', uploadedFile);
+            formData.append('mapping', JSON.stringify(columnMapping));
+            formData.append('model_config', JSON.stringify(modelConfig));
+
+            const response = await CustomFetch('/ajax/import/preview-mapping', {
+                method: 'POST',
+                body: formData,
+            });
+
+            if (response.success) {
+                setPreviewData(response.preview);
+                setValidationSummary(response.validation_summary);
+                setCurrentStep(3);
+            } else {
+                toast.error(response.message || 'Failed to preview data');
+            }
+        } catch (error) {
+            console.error('Preview error:', error);
+            toast.error('Error previewing data');
+        } finally {
+            setLoading(false);
+        }
+    }
+
+    async function handleImport() {
+        setLoading(true);
+        
+        try {
+            const formData = new FormData();
+            formData.append('file', uploadedFile);
+            formData.append('mapping', JSON.stringify(columnMapping));
+            formData.append('model_config', JSON.stringify(modelConfig));
+            formData.append('target_model', targetModel);
+            if (parentId) formData.append('parent_id', parentId.toString());
+            if (relationKey) formData.append('relation_key', relationKey);
+
+            const response = await CustomFetch('/ajax/import/process', {
+                method: 'POST',
+                body: formData,
+            });
+
+            if (response.success) {
+                setImportResults(response);
+                setCurrentStep(4);
+                toast.success(`Import completed! ${response.imported} records imported successfully.`);
+            } else {
+                toast.error(response.message || 'Import failed');
+            }
+        } catch (error) {
+            console.error('Import error:', error);
+            toast.error('Error during import');
+        } finally {
+            setLoading(false);
+        }
+    }
+
+    const handleClose = () => {
+        if (importResults && importResults.imported > 0 && onComplete) {
+            onComplete();
+        }
+        onClose();
+    };
+
+    const canGoNext = () => {
+        switch (currentStep) {
+            case 1: return fileData !== null;
+            case 2: return canProceedToPreview();
+            case 3: return validationSummary && validationSummary.valid_rows > 0;
+            default: return false;
+        }
+    };
+
+    const handleNext = () => {
+        switch (currentStep) {
+            case 2:
+                handlePreviewMapping();
+                break;
+            case 3:
+                handleImport();
+                break;
+            default:
+                setCurrentStep(prev => prev + 1);
+        }
+    };
+
+    const handleBack = () => {
+        setCurrentStep(prev => Math.max(1, prev - 1));
+    };
+
+    const renderStepIndicator = () => (
+        <div className={styles.stepIndicator}>
+            {steps.map((step, index) => (
+                <div key={step.id} className={styles.stepContainer}>
+                    <div className={`${styles.step} ${currentStep >= step.id ? styles.active : ''}`}>
+                        {step.icon}
+                    </div>
+                    <div className={styles.stepInfo}>
+                        <div className={styles.stepTitle}>{step.title}</div>
+                        <div className={styles.stepDescription}>{step.description}</div>
+                    </div>
+                    {index < steps.length - 1 && (
+                        <div className={`${styles.stepConnector} ${currentStep > step.id ? styles.completed : ''}`} />
+                    )}
+                </div>
+            ))}
+        </div>
+    );
+
+    const renderUploadStep = () => (
+        <div className={styles.uploadStep}>
+            <div {...getRootProps()} className={`${styles.dropzone} ${isDragActive ? styles.active : ''}`}>
+                <input {...getInputProps()} />
+                <Upload size={48} className={styles.uploadIcon} />
+                <h3>Drop your file here, or click to browse</h3>
+                <p>Supports CSV, XLS, and XLSX files (max 10MB)</p>
+                {uploadedFile && (
+                    <div className={styles.fileInfo}>
+                        <FileText size={20} />
+                        <span>{uploadedFile.name}</span>
+                    </div>
+                )}
+            </div>
+            
+            <div className={styles.templateSection}>
+                <h4>Need a template?</h4>
+                <p>Download a template with the correct column headers:</p>
+                <button 
+                    type="button" 
+                    className={styles.templateButton}
+                    onClick={() => downloadTemplate()}
+                >
+                    <Download size={16} />
+                    Download Template
+                </button>
+            </div>
+        </div>
+    );
+
+    const downloadTemplate = () => {
+        const headers = modelConfig.map(field => field.label);
+        const csvContent = headers.join(',') + '\n';
+        const blob = new Blob([csvContent], { type: 'text/csv' });
+        const url = window.URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `${title.toLowerCase().replace(/\s+/g, '_')}_template.csv`;
+        a.click();
+        window.URL.revokeObjectURL(url);
+    };
+
+    const renderMappingStep = () => (
+        <div className={styles.mappingStep}>
+            <div className={styles.mappingHeader}>
+                <h3>Map File Columns to Data Fields</h3>
+                <p>Match columns from your file to the appropriate data fields. Required fields are marked with *</p>
+            </div>
+            
+            <div className={styles.mappingContainer}>
+                <div className={styles.mappingList}>
+                    {fileData.headers.map(header => (
+                        <div key={header} className={styles.mappingRow}>
+                            <div className={styles.fileColumn}>
+                                <strong>{header}</strong>
+                                {fileData.sample_data.length > 0 && (
+                                    <div className={styles.sampleValue}>
+                                        Example: "{fileData.sample_data[0][header] || 'N/A'}"
+                                    </div>
+                                )}
+                            </div>
+                            
+                            <ArrowRight size={20} className={styles.arrow} />
+                            
+                            <div className={styles.fieldColumn}>
+                                <Select
+                                    value={columnMapping[header] || ''}
+                                    onChange={(value) => handleMappingChange(header, value)}
+                                    options={[
+                                        { value: '', label: 'Skip Column' },
+                                        ...modelConfig.map(field => ({
+                                            value: field.id,
+                                            label: `${field.label}${field.required ? ' *' : ''}`,
+                                            disabled: getMappedFields().includes(field.id) && columnMapping[header] !== field.id
+                                        }))
+                                    ]}
+                                    placeholder="Select field..."
+                                />
+                            </div>
+                        </div>
+                    ))}
+                </div>
+                
+                <div className={styles.mappingSummary}>
+                    <h4>Mapping Summary</h4>
+                    <div className={styles.summaryItem}>
+                        <span>Total Columns:</span>
+                        <span>{fileData.headers.length}</span>
+                    </div>
+                    <div className={styles.summaryItem}>
+                        <span>Mapped Columns:</span>
+                        <span>{getMappedFields().length}</span>
+                    </div>
+                    <div className={styles.summaryItem}>
+                        <span>Required Fields:</span>
+                        <span>{getRequiredFields().length}</span>
+                    </div>
+                    
+                    {getUnmappedRequiredFields().length > 0 && (
+                        <div className={styles.missingFields}>
+                            <AlertTriangle size={16} />
+                            <div>
+                                <strong>Missing Required Fields:</strong>
+                                <ul>
+                                    {getUnmappedRequiredFields().map(field => {
+                                        const fieldConfig = modelConfig.find(f => f.id === field);
+                                        return <li key={field}>{fieldConfig?.label || field}</li>;
+                                    })}
+                                </ul>
+                            </div>
+                        </div>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+
+    const renderPreviewStep = () => (
+        <div className={styles.previewStep}>
+            <div className={styles.previewHeader}>
+                <h3>Data Preview</h3>
+                <p>Review the mapped data before importing. Only the first 10 rows are shown.</p>
+            </div>
+            
+            {validationSummary && (
+                <div className={styles.validationSummary}>
+                    <div className={styles.summaryCards}>
+                        <div className={styles.summaryCard}>
+                            <CheckCircle size={24} className={styles.successIcon} />
+                            <div>
+                                <div className={styles.number}>{validationSummary.valid_rows}</div>
+                                <div className={styles.label}>Valid Rows</div>
+                            </div>
+                        </div>
+                        
+                        <div className={styles.summaryCard}>
+                            <AlertTriangle size={24} className={styles.warningIcon} />
+                            <div>
+                                <div className={styles.number}>{validationSummary.invalid_rows}</div>
+                                <div className={styles.label}>Invalid Rows</div>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    {validationSummary.errors.length > 0 && (
+                        <div className={styles.errorList}>
+                            <h4>Validation Errors:</h4>
+                            <div className={styles.errors}>
+                                {validationSummary.errors.slice(0, 5).map((error, index) => (
+                                    <div key={index} className={styles.errorItem}>
+                                        <strong>Row {error.row}:</strong>
+                                        <ul>
+                                            {error.errors.map((err, i) => <li key={i}>{err}</li>)}
+                                        </ul>
+                                    </div>
+                                ))}
+                                {validationSummary.errors.length > 5 && (
+                                    <div className={styles.moreErrors}>
+                                        ... and {validationSummary.errors.length - 5} more errors
+                                    </div>
+                                )}
+                            </div>
+                        </div>
+                    )}
+                </div>
+            )}
+            
+            <div className={styles.previewTable}>
+                <div className={styles.tableContainer}>
+                    <table>
+                        <thead>
+                            <tr>
+                                <th>Status</th>
+                                {getMappedFields().map(field => {
+                                    const fieldConfig = modelConfig.find(f => f.id === field);
+                                    return <th key={field}>{fieldConfig?.label || field}</th>;
+                                })}
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {previewData.map((row, index) => (
+                                <tr key={index} className={row.valid ? styles.validRow : styles.invalidRow}>
+                                    <td>
+                                        {row.valid ? (
+                                            <CheckCircle size={16} className={styles.successIcon} />
+                                        ) : (
+                                            <AlertTriangle size={16} className={styles.errorIcon} />
+                                        )}
+                                    </td>
+                                    {getMappedFields().map(field => (
+                                        <td key={field}>{row.mapped[field] || '-'}</td>
+                                    ))}
+                                </tr>
+                            ))}
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+    );
+
+    const renderImportStep = () => (
+        <div className={styles.importStep}>
+            {loading ? (
+                <div className={styles.importing}>
+                    <RefreshCw size={48} className={styles.spinner} />
+                    <h3>Importing data...</h3>
+                    <p>Please wait while we process your data.</p>
+                </div>
+            ) : (
+                <div className={styles.importResults}>
+                    <CheckCircle size={64} className={styles.successIcon} />
+                    <h3>Import Completed!</h3>
+                    
+                    {importResults && (
+                        <div className={styles.resultsSummary}>
+                            <div className={styles.resultsGrid}>
+                                <div className={styles.resultItem}>
+                                    <div className={styles.resultNumber}>{importResults.imported}</div>
+                                    <div className={styles.resultLabel}>Records Imported</div>
+                                </div>
+                                
+                                <div className={styles.resultItem}>
+                                    <div className={styles.resultNumber}>{importResults.errors?.length || 0}</div>
+                                    <div className={styles.resultLabel}>Errors</div>
+                                </div>
+                                
+                                <div className={styles.resultItem}>
+                                    <div className={styles.resultNumber}>{importResults.skipped}</div>
+                                    <div className={styles.resultLabel}>Skipped</div>
+                                </div>
+                            </div>
+                            
+                            {importResults.errors && importResults.errors.length > 0 && (
+                                <div className={styles.importErrors}>
+                                    <h4>Import Errors:</h4>
+                                    <div className={styles.errorList}>
+                                        {importResults.errors.slice(0, 5).map((error, index) => (
+                                            <div key={index} className={styles.errorItem}>
+                                                <strong>Row {error.row}:</strong>
+                                                <ul>
+                                                    {error.errors.map((err, i) => <li key={i}>{err}</li>)}
+                                                </ul>
+                                            </div>
+                                        ))}
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    )}
+                </div>
+            )}
+        </div>
+    );
+
+    const renderCurrentStep = () => {
+        switch (currentStep) {
+            case 1: return renderUploadStep();
+            case 2: return renderMappingStep();
+            case 3: return renderPreviewStep();
+            case 4: return renderImportStep();
+            default: return null;
+        }
+    };
+
+    return (
+        <StandardModal
+            isOpen={isOpen}
+            onClose={handleClose}
+            title={title}
+            size="xl"
+            className={styles.importWizardModal}
+        >
+            <div className={styles.modalContent}>
+                {renderStepIndicator()}
+                
+                <div className={styles.stepContent}>
+                    {renderCurrentStep()}
+                </div>
+                
+                <div className={styles.modalFooter}>
+                    <div className={styles.footerLeft}>
+                        {currentStep > 1 && currentStep < 4 && (
+                            <button
+                                type="button"
+                                onClick={handleBack}
+                                className={styles.backButton}
+                                disabled={loading}
+                            >
+                                <ArrowLeft size={16} />
+                                Back
+                            </button>
+                        )}
+                    </div>
+                    
+                    <div className={styles.footerRight}>
+                        {currentStep < 4 ? (
+                            <button
+                                type="button"
+                                onClick={handleNext}
+                                className={styles.nextButton}
+                                disabled={!canGoNext() || loading}
+                            >
+                                {loading ? (
+                                    <>
+                                        <RefreshCw size={16} className={styles.spinner} />
+                                        Processing...
+                                    </>
+                                ) : (
+                                    <>
+                                        {currentStep === 3 ? 'Import' : 'Next'}
+                                        <ArrowRight size={16} />
+                                    </>
+                                )}
+                            </button>
+                        ) : (
+                            <button
+                                type="button"
+                                onClick={handleClose}
+                                className={styles.finishButton}
+                            >
+                                Finish
+                            </button>
+                        )}
+                    </div>
+                </div>
+            </div>
+        </StandardModal>
+    );
+};
+
+export default ImportWizardModal;

package/src/components/styles/ImportWizardModal.module.scss

@@ -0,0 +1,622 @@
+.importWizardModal {
+    .modalContent {
+        display: flex;
+        flex-direction: column;
+        height: 80vh;
+        max-height: 800px;
+    }
+}
+
+.stepIndicator {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem 0;
+    border-bottom: 1px solid #e5e7eb;
+    margin-bottom: 2rem;
+    
+    .stepContainer {
+        display: flex;
+        align-items: center;
+        position: relative;
+        
+        &:not(:last-child) {
+            margin-right: 2rem;
+        }
+    }
+    
+    .step {
+        width: 48px;
+        height: 48px;
+        border-radius: 50%;
+        border: 2px solid #d1d5db;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: white;
+        color: #6b7280;
+        transition: all 0.3s ease;
+        
+        &.active {
+            border-color: #3b82f6;
+            background: #3b82f6;
+            color: white;
+        }
+    }
+    
+    .stepInfo {
+        margin-left: 1rem;
+        
+        .stepTitle {
+            font-weight: 600;
+            font-size: 0.95rem;
+            color: #111827;
+        }
+        
+        .stepDescription {
+            font-size: 0.85rem;
+            color: #6b7280;
+        }
+    }
+    
+    .stepConnector {
+        width: 40px;
+        height: 2px;
+        background: #d1d5db;
+        margin: 0 1rem;
+        transition: background-color 0.3s ease;
+        
+        &.completed {
+            background: #3b82f6;
+        }
+    }
+}
+
+.stepContent {
+    flex: 1;
+    overflow-y: auto;
+    padding: 0 1rem;
+}
+
+// Upload Step
+.uploadStep {
+    .dropzone {
+        border: 2px dashed #d1d5db;
+        border-radius: 12px;
+        padding: 3rem 2rem;
+        text-align: center;
+        cursor: pointer;
+        transition: all 0.3s ease;
+        background: #fafafa;
+        
+        &:hover, &.active {
+            border-color: #3b82f6;
+            background: #f0f8ff;
+        }
+        
+        .uploadIcon {
+            color: #6b7280;
+            margin-bottom: 1rem;
+        }
+        
+        h3 {
+            margin: 0 0 0.5rem 0;
+            color: #111827;
+            font-size: 1.25rem;
+        }
+        
+        p {
+            margin: 0;
+            color: #6b7280;
+            font-size: 0.95rem;
+        }
+        
+        .fileInfo {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.5rem;
+            margin-top: 1rem;
+            padding: 0.75rem 1rem;
+            background: #e0f2fe;
+            border-radius: 8px;
+            color: #0369a1;
+        }
+    }
+    
+    .templateSection {
+        margin-top: 2rem;
+        padding: 1.5rem;
+        background: #f9fafb;
+        border-radius: 8px;
+        text-align: center;
+        
+        h4 {
+            margin: 0 0 0.5rem 0;
+            color: #111827;
+        }
+        
+        p {
+            margin: 0 0 1rem 0;
+            color: #6b7280;
+            font-size: 0.9rem;
+        }
+        
+        .templateButton {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.75rem 1.25rem;
+            background: #3b82f6;
+            color: white;
+            border: none;
+            border-radius: 6px;
+            cursor: pointer;
+            font-size: 0.9rem;
+            transition: background-color 0.2s ease;
+            
+            &:hover {
+                background: #2563eb;
+            }
+        }
+    }
+}
+
+// Mapping Step
+.mappingStep {
+    .mappingHeader {
+        margin-bottom: 2rem;
+        
+        h3 {
+            margin: 0 0 0.5rem 0;
+            color: #111827;
+        }
+        
+        p {
+            margin: 0;
+            color: #6b7280;
+            font-size: 0.95rem;
+        }
+    }
+    
+    .mappingContainer {
+        display: grid;
+        grid-template-columns: 1fr 300px;
+        gap: 2rem;
+    }
+    
+    .mappingList {
+        .mappingRow {
+            display: grid;
+            grid-template-columns: 1fr auto 1fr;
+            gap: 1rem;
+            align-items: center;
+            padding: 1rem;
+            border: 1px solid #e5e7eb;
+            border-radius: 8px;
+            margin-bottom: 1rem;
+            background: white;
+            
+            .fileColumn {
+                strong {
+                    display: block;
+                    color: #111827;
+                    margin-bottom: 0.25rem;
+                }
+                
+                .sampleValue {
+                    font-size: 0.8rem;
+                    color: #6b7280;
+                    font-style: italic;
+                }
+            }
+            
+            .arrow {
+                color: #6b7280;
+            }
+            
+            .fieldColumn {
+                select, .select-container {
+                    width: 100%;
+                }
+            }
+        }
+    }
+    
+    .mappingSummary {
+        background: #f9fafb;
+        border-radius: 8px;
+        padding: 1.5rem;
+        
+        h4 {
+            margin: 0 0 1rem 0;
+            color: #111827;
+        }
+        
+        .summaryItem {
+            display: flex;
+            justify-content: space-between;
+            padding: 0.5rem 0;
+            border-bottom: 1px solid #e5e7eb;
+            
+            &:last-child {
+                border-bottom: none;
+            }
+        }
+        
+        .missingFields {
+            margin-top: 1rem;
+            padding: 1rem;
+            background: #fef2f2;
+            border-radius: 6px;
+            color: #dc2626;
+            
+            display: flex;
+            align-items: flex-start;
+            gap: 0.5rem;
+            
+            ul {
+                margin: 0.5rem 0 0 0;
+                padding-left: 1rem;
+                
+                li {
+                    margin-bottom: 0.25rem;
+                }
+            }
+        }
+    }
+}
+
+// Preview Step
+.previewStep {
+    .previewHeader {
+        margin-bottom: 2rem;
+        
+        h3 {
+            margin: 0 0 0.5rem 0;
+            color: #111827;
+        }
+        
+        p {
+            margin: 0;
+            color: #6b7280;
+            font-size: 0.95rem;
+        }
+    }
+    
+    .validationSummary {
+        margin-bottom: 2rem;
+        
+        .summaryCards {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 1rem;
+            margin-bottom: 1rem;
+            
+            .summaryCard {
+                display: flex;
+                align-items: center;
+                gap: 1rem;
+                padding: 1.5rem;
+                background: white;
+                border-radius: 8px;
+                border: 1px solid #e5e7eb;
+                
+                .number {
+                    font-size: 1.75rem;
+                    font-weight: bold;
+                    color: #111827;
+                }
+                
+                .label {
+                    font-size: 0.9rem;
+                    color: #6b7280;
+                }
+                
+                .successIcon {
+                    color: #059669;
+                }
+                
+                .warningIcon {
+                    color: #d97706;
+                }
+            }
+        }
+        
+        .errorList {
+            background: #fef2f2;
+            border-radius: 8px;
+            padding: 1rem;
+            
+            h4 {
+                margin: 0 0 1rem 0;
+                color: #dc2626;
+            }
+            
+            .errors {
+                max-height: 200px;
+                overflow-y: auto;
+                
+                .errorItem {
+                    margin-bottom: 1rem;
+                    
+                    strong {
+                        color: #dc2626;
+                    }
+                    
+                    ul {
+                        margin: 0.5rem 0 0 1rem;
+                        
+                        li {
+                            color: #991b1b;
+                            font-size: 0.9rem;
+                        }
+                    }
+                }
+                
+                .moreErrors {
+                    color: #6b7280;
+                    font-style: italic;
+                    text-align: center;
+                    padding-top: 1rem;
+                    border-top: 1px solid #f3f4f6;
+                }
+            }
+        }
+    }
+    
+    .previewTable {
+        border: 1px solid #e5e7eb;
+        border-radius: 8px;
+        overflow: hidden;
+        
+        .tableContainer {
+            overflow-x: auto;
+            max-height: 400px;
+            
+            table {
+                width: 100%;
+                border-collapse: collapse;
+                
+                th, td {
+                    padding: 0.75rem;
+                    text-align: left;
+                    border-bottom: 1px solid #e5e7eb;
+                    font-size: 0.9rem;
+                }
+                
+                th {
+                    background: #f9fafb;
+                    font-weight: 600;
+                    color: #111827;
+                    position: sticky;
+                    top: 0;
+                    z-index: 10;
+                }
+                
+                .validRow {
+                    &:hover {
+                        background: #f0fdf4;
+                    }
+                }
+                
+                .invalidRow {
+                    background: #fef2f2;
+                    
+                    &:hover {
+                        background: #fecaca;
+                    }
+                }
+                
+                .successIcon {
+                    color: #059669;
+                }
+                
+                .errorIcon {
+                    color: #dc2626;
+                }
+            }
+        }
+    }
+}
+
+// Import Step
+.importStep {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 400px;
+    
+    .importing {
+        text-align: center;
+        
+        .spinner {
+            animation: spin 1s linear infinite;
+            color: #3b82f6;
+            margin-bottom: 1rem;
+        }
+        
+        h3 {
+            margin: 0 0 0.5rem 0;
+            color: #111827;
+        }
+        
+        p {
+            margin: 0;
+            color: #6b7280;
+        }
+    }
+    
+    .importResults {
+        text-align: center;
+        width: 100%;
+        
+        .successIcon {
+            color: #059669;
+            margin-bottom: 1rem;
+        }
+        
+        h3 {
+            margin: 0 0 2rem 0;
+            color: #111827;
+        }
+        
+        .resultsSummary {
+            .resultsGrid {
+                display: grid;
+                grid-template-columns: repeat(3, 1fr);
+                gap: 1rem;
+                margin-bottom: 2rem;
+                
+                .resultItem {
+                    padding: 1.5rem;
+                    background: white;
+                    border: 1px solid #e5e7eb;
+                    border-radius: 8px;
+                    
+                    .resultNumber {
+                        font-size: 2rem;
+                        font-weight: bold;
+                        color: #111827;
+                        margin-bottom: 0.25rem;
+                    }
+                    
+                    .resultLabel {
+                        color: #6b7280;
+                        font-size: 0.9rem;
+                    }
+                }
+            }
+            
+            .importErrors {
+                background: #fef2f2;
+                border-radius: 8px;
+                padding: 1rem;
+                text-align: left;
+                
+                h4 {
+                    margin: 0 0 1rem 0;
+                    color: #dc2626;
+                }
+                
+                .errorList {
+                    max-height: 200px;
+                    overflow-y: auto;
+                    
+                    .errorItem {
+                        margin-bottom: 1rem;
+                        
+                        strong {
+                            color: #dc2626;
+                        }
+                        
+                        ul {
+                            margin: 0.5rem 0 0 1rem;
+                            
+                            li {
+                                color: #991b1b;
+                                font-size: 0.9rem;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+// Footer
+.modalFooter {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 1.5rem 0 0 0;
+    border-top: 1px solid #e5e7eb;
+    margin-top: 2rem;
+    
+    .footerLeft, .footerRight {
+        display: flex;
+        gap: 1rem;
+    }
+    
+    .backButton, .nextButton, .finishButton {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.75rem 1.5rem;
+        border-radius: 6px;
+        cursor: pointer;
+        font-weight: 500;
+        transition: all 0.2s ease;
+        border: none;
+        
+        &:disabled {
+            opacity: 0.6;
+            cursor: not-allowed;
+        }
+        
+        .spinner {
+            animation: spin 1s linear infinite;
+        }
+    }
+    
+    .backButton {
+        background: #f3f4f6;
+        color: #374151;
+        
+        &:hover:not(:disabled) {
+            background: #e5e7eb;
+        }
+    }
+    
+    .nextButton, .finishButton {
+        background: #3b82f6;
+        color: white;
+        
+        &:hover:not(:disabled) {
+            background: #2563eb;
+        }
+    }
+}
+
+@keyframes spin {
+    from {
+        transform: rotate(0deg);
+    }
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+// Responsive
+@media (max-width: 768px) {
+    .stepIndicator {
+        flex-direction: column;
+        gap: 1rem;
+        
+        .stepContainer {
+            margin-right: 0;
+        }
+        
+        .stepConnector {
+            display: none;
+        }
+    }
+    
+    .mappingContainer {
+        grid-template-columns: 1fr;
+    }
+    
+    .mappingRow {
+        grid-template-columns: 1fr;
+        gap: 0.5rem;
+        
+        .arrow {
+            transform: rotate(90deg);
+        }
+    }
+    
+    .resultsGrid {
+        grid-template-columns: 1fr;
+    }
+}

package/src/index.js

@@ -38,6 +38,7 @@ import AudioPlayer from './components/controls/AudioPlayer';
 import GalleryModal from './components/modals/GalleryModal';
 import ImageModal from './components/ImageModal';
 import DatePickerPortal from './components/utils/DatePickerPortal';
+import ImportWizardModal from './components/ImportWizardModal';
 export * from './components/columns/ColumnRenderers.jsx';
 
 /** Auth Specific Components */
@@ -137,6 +138,7 @@ export {
     GenericQuote,
     GenericReport,
     GenericSort,
+    ImportWizardModal,
     Loader,
     Login,
     MergeEntity,