Implement a CSV import directly in the theme

Author: corsacca

dt-import/FEATURE_IMPLEMENTATION.md

@@ -0,0 +1,128 @@
+# Value Mapping Implementation for Key Select and Multi Select Fields
+
+## Overview
+
+This implementation adds comprehensive value mapping functionality for `key_select` and `multi_select` fields in the DT Import system. Users can now map CSV values to the available field options for these field types during the field mapping step.
+
+## Key Features Implemented
+
+### 1. Enhanced Value Mapping Modal
+- **Real data fetching**: Fetches actual CSV column data and field options from the server
+- **Unique value detection**: Shows all unique values found in the CSV column
+- **Flexible mapping**: Users can map, skip, or ignore specific CSV values
+- **Auto-mapping**: Intelligent auto-mapping with fuzzy matching for similar values
+- **Batch operations**: Clear all mappings or auto-map similar values with one click
+
+### 2. New API Endpoints
+
+#### Get Field Options (`/dt-import/v2/{post_type}/field-options`)
+- **Method**: GET
+- **Parameters**: `field_key` (required)
+- **Purpose**: Fetches available options for key_select and multi_select fields
+- **Returns**: Formatted key-value pairs of field options
+
+#### Get Column Data (`/dt-import/v2/{session_id}/column-data`)
+- **Method**: GET  
+- **Parameters**: `column_index` (required)
+- **Purpose**: Fetches unique values and sample data from a specific CSV column
+- **Returns**: Unique values, sample data, and total count
+
+### 3. Enhanced JavaScript Functionality
+
+#### DTImportModals Class Extensions
+- `getColumnCSVData()`: Fetches CSV column data from session
+- `getFieldOptions()`: Fetches field options from server API
+- `autoMapValues()`: Intelligent auto-mapping with fuzzy matching
+- `clearAllMappings()`: Clears all value mappings
+- `updateMappingCount()`: Live count of mapped vs unmapped values
+
+### 4. User Interface Improvements
+
+#### Value Mapping Modal
+- **Enhanced layout**: Wider modal (800px) with better spacing
+- **Control buttons**: Auto-map and clear all functionality
+- **Live feedback**: Real-time mapping count and progress indicator
+- **Better data display**: Shows total unique values found
+- **Sticky headers**: Table headers remain visible while scrolling
+
+#### Field Mapping Integration
+- **Seamless integration**: "Configure Values" button appears for key_select/multi_select fields
+- **Mapping indicator**: Button shows count of mapped values
+- **Field-specific options**: Only shows for applicable field types
+
+### 5. Data Processing Enhancements
+
+#### Value Mapping Storage
+```php
+// Field mapping structure now supports value mappings
+$field_mappings[column_index] = [
+    'field_key' => 'field_name',
+    'column_index' => 0,
+    'value_mapping' => [
+        'csv_value_1' => 'dt_option_key_1',
+        'csv_value_2' => 'dt_option_key_2',
+        // ...
+    ]
+];
+```
+
+#### Processing Logic
+- **key_select fields**: Maps single CSV values to single DT options
+- **multi_select fields**: Splits semicolon-separated values and maps each
+- **Fallback handling**: Direct option matching if no mapping defined
+- **Error handling**: Clear error messages for invalid mappings
+
+### 6. CSS Styling
+
+#### New CSS Classes
+- `.value-mapping-modal`: Enhanced modal styling
+- `.value-mapping-controls`: Action button container
+- `.value-mapping-container`: Scrollable table container
+- `.value-mapping-select`: Styled dropdown selects
+- `.mapping-summary`: Live mapping progress display
+
+## User Workflow
+
+1. **Field Selection**: User selects a key_select or multi_select field for a CSV column
+2. **Configure Values**: "Configure Values" button appears in field-specific options
+3. **Modal Display**: Click opens modal showing all unique CSV values
+4. **Value Mapping**: User maps CSV values to available field options
+5. **Auto-mapping**: Optional auto-mapping for similar values
+6. **Save Mapping**: Mappings are saved and stored with field configuration
+7. **Import Processing**: Values are transformed according to mappings during import
+
+## Technical Implementation Details
+
+### Backend Processing
+- **DT_Import_Mapping::get_unique_column_values()**: Extracts unique values from CSV
+- **Field validation**: Ensures mapped values are valid field options
+- **Import processing**: Applies value mappings during record creation
+
+### Frontend Integration
+- **Modal system**: Reusable modal framework for field configuration
+- **Event handling**: Proper event delegation for dynamic content
+- **Error handling**: User-friendly error messages and validation
+- **State management**: Maintains mapping state across modal interactions
+
+### API Integration
+- **REST API**: Follows WordPress REST API standards
+- **Authentication**: Uses WordPress nonce verification
+- **Error responses**: Standardized error response format
+- **Data validation**: Server-side validation of all inputs
+
+## Benefits
+
+1. **Data Integrity**: Ensures CSV values map to valid DT field options
+2. **User Experience**: Intuitive interface with helpful auto-mapping
+3. **Flexibility**: Supports skipping unwanted values or mapping multiple values
+4. **Efficiency**: Batch operations for common mapping tasks
+5. **Validation**: Real-time feedback and error prevention
+
+## Future Enhancements
+
+1. **Value Suggestions**: AI-powered mapping suggestions based on content analysis
+2. **Template Mapping**: Save and reuse value mappings for similar imports
+3. **Bulk Import**: Handle very large CSV files with chunked processing
+4. **Advanced Matching**: Regex or pattern-based value matching
+
+This implementation provides a robust, user-friendly solution for mapping CSV values to DT field options, significantly improving the import experience for key_select and multi_select fields.