importers_stepper.js

// Bulk Import Stepper - Multi-step wizard for CSV/ZIP imports
// Handles file uploads, validation, settings, and review steps
//
// DEPENDENCIES:
// - jQuery (global)
// - BulkraxUtils (from bulkrax_utils.js - must load first)
//
// TABLE OF CONTENTS:
// - Utility Functions
// - Constants & Configuration
// - State Management
// - Initialization
// - Event Binding
// - File Validation & Utilities
// - File Upload Handlers
// - Demo Scenarios
// - Upload State Management
// - Validation
// - Validation Results Rendering
// - Import Summary & Hierarchy
// - Settings & Navigation
// - Form Submission & Success State
// - Notification Functions

; (function ($, Utils) {
  'use strict'

  // Import utilities from BulkraxUtils
  var escapeHtml = Utils.escapeHtml
  var formatFileSize = Utils.formatFileSize
  var normalizeBoolean = Utils.normalizeBoolean
  var t = Utils.t

  // ============================================================================
  // UTILITY FUNCTIONS
  // ============================================================================

  // Delays function execution until after 'wait' milliseconds have passed
  // since the last time it was invoked
  function debounce(func, wait) {
    var timeout
    return function debounced() {
      var context = this
      var args = arguments
      clearTimeout(timeout)
      timeout = setTimeout(function () {
        func.apply(context, args)
      }, wait)
    }
  }

  // ============================================================================
  // CONSTANTS & CONFIGURATION
  // ============================================================================

  var CONSTANTS = {
    // File upload limits
    MAX_FILES: 2,
    // Import size thresholds
    IMPORT_SIZE_OPTIMAL: 100,
    IMPORT_SIZE_MODERATE: 500,
    IMPORT_SIZE_LARGE: 1000,

    // File types
    ALLOWED_EXTENSIONS: ['.csv', '.zip'],

    // Upload states
    UPLOAD_STATES: {
      EMPTY: 'empty',
      CSV_ONLY: 'csv_only',
      ZIP_FILES_ONLY: 'zip_files_only',
      ZIP_WITH_CSV: 'zip_with_csv',
      CSV_AND_ZIP: 'csv_and_zip'
    },

    // Animation timings
    ANIMATION_SPEED: 200,
    SCROLL_SPEED: 300,
    VALIDATION_DELAY: 2000,
    NOTIFICATION_FADE_SPEED: 300,
    DEBOUNCE_DELAY: 300,

    // AJAX timeouts (in milliseconds)
    AJAX_TIMEOUT_SHORT: 10000, // 10 seconds for simple requests
    AJAX_TIMEOUT_LONG: 120000, // 2 minutes for validation

    // Chunked upload settings (matches Hyrax v1 uploader)
    CHUNK_SIZE: 10000000, // 10 MB per chunk
    UPLOAD_URL: '/uploads/',

    // Hierarchy rendering limits
    MAX_TREE_DEPTH: 50, // Prevent stack overflow on deeply nested hierarchies

    // Validation issue list cap — accordion shows up to this many items; full list is in the downloaded CSV
    MAX_ISSUE_ITEMS: 10,

    // API endpoints
    ENDPOINTS: {
      DEMO_SCENARIOS: '/importers/guided_import/demo_scenarios',
      VALIDATE: '/importers/guided_import/validate',
      DOWNLOAD_VALIDATION_ERRORS: '/importers/guided_import/download_validation_errors'
    }
  }

  // ============================================================================
  // STATE MANAGEMENT
  // ============================================================================

  var StepperState = {
    currentStep: 1,
    uploadedFiles: [],
    uploadState: CONSTANTS.UPLOAD_STATES.EMPTY,
    uploadMode: 'upload', // 'upload' or 'file_path'
    validated: false,
    validationData: null,
    warningsAcked: false,
    skipValidation: false, // Flag to skip validation step
    isAddingFiles: false, // Flag to track if we're adding files vs replacing
    demoScenario: null, // Track which demo scenario is loaded
    demoScenariosData: null, // Cached demo scenarios JSON from server
    uploadsInProgress: 0,
    adminSetId: '',
    adminSetName: '',
    settings: {
      name: '',
      visibility: 'open',
      rightsStatement: '',
      limit: ''
    }
  }

  // Guard flag to prevent rebinding events on every page load (Turbolinks)
  var eventsInitialized = false

  // ============================================================================
  // INITIALIZATION
  // ============================================================================

  // Initialize on page load
  function initBulkImportStepper() {
    if ($('#bulk-import-stepper-form').length === 0) {
      return
    }

    eventsInitialized = false

    bindEvents()
    initAdminSetState()
    updateDownloadTemplateLink()
    updateStepperUI()
    initVisibilityCards()
    setDefaultImportName()
  }

  // ============================================================================
  // EVENT BINDING
  // ============================================================================

  // Bind all event handlers
  function bindEvents() {
    // Only bind events once, even if initBulkImportStepper runs multiple times
    if (eventsInitialized) {
      return // Events already bound, skip rebinding
    }

    // File upload - main dropzone
    // <label for="file-input"> is needed for accessibility but also opens the file selector when clicked
    // this will prevent that behavior while maintaining accessibility
    $('.upload-dropzone').on('click', function (e) {
      if (e.target.id === 'file-input') return
      e.preventDefault()
      openMainFilePicker()
    })
    // role="button" in WCAG 2.1 AA requires keyboard interaction for enter and space key
    // this allows user to open the file picker with the space key when the dropzone is focused
    $('.upload-dropzone').on('keydown', function (e) {
      if (e.key === ' ') {
        e.preventDefault()
        openMainFilePicker()
      }
    })

    // Delegated event handlers for dynamic content
    // These only need to be bound once since they listen on stable parent containers
    bindDelegatedEvents()

    // File upload - add another dropzone
    // <label for="file-input-additional"> is needed for accessibility but also opens the file selector when clicked
    // this will prevent that behavior while maintaining accessibility
    $('.upload-dropzone-small').on('click', function (e) {
      e.preventDefault()
      openAdditionalFilePicker()
    })
    // role="button" in WCAG 2.1 AA requires keyboard interaction for enter and space key
    // this allows user to open the file picker with the space key when the dropzone is focused
    $('.upload-dropzone-small').on('keydown', function (e) {
      if (e.key === ' ') {
        e.preventDefault()
        openAdditionalFilePicker()
      }
    })

    $('#file-input').on('change', function () {
      handleFileSelect(StepperState.isAddingFiles)
      StepperState.isAddingFiles = false // Reset flag after handling
    })

    // Drag and drop - main dropzone
    $('.upload-dropzone').on('dragover', function (e) {
      e.preventDefault()
      $(this).addClass('dragover')
    })

    $('.upload-dropzone').on('dragleave', function (e) {
      e.preventDefault()
      $(this).removeClass('dragover')
    })

    $('.upload-dropzone').on('drop', function (e) {
      e.preventDefault()
      $(this).removeClass('dragover')
      var droppedFiles = e.originalEvent.dataTransfer.files
      if (droppedFiles.length > 0) {
        // Prepare files array (up to MAX_FILES total)
        var maxFiles = Math.min(droppedFiles.length, CONSTANTS.MAX_FILES)
        var filesToAdd = []
        for (var i = 0; i < maxFiles; i++) {
          filesToAdd.push(droppedFiles[i])
        }

        // Try to set files on input element (with browser compatibility fallback)
        setInputFiles($('#file-input')[0], filesToAdd)

        handleFileSelect(false) // Drag and drop replaces files

        // Show warning if more than MAX_FILES were dropped
        if (droppedFiles.length > CONSTANTS.MAX_FILES) {
          showNotification(
            t('only_first_files', { count: CONSTANTS.MAX_FILES, max: CONSTANTS.MAX_FILES })
          )
        }
      }
    })

    // Drag and drop - small "add another" dropzone
    $('.upload-dropzone-small').on('dragover', function (e) {
      e.preventDefault()
      $(this).addClass('dragover')
    })

    $('.upload-dropzone-small').on('dragleave', function (e) {
      e.preventDefault()
      $(this).removeClass('dragover')
    })

    $('.upload-dropzone-small').on('drop', function (e) {
      e.preventDefault()
      $(this).removeClass('dragover')
      var droppedFiles = e.originalEvent.dataTransfer.files
      if (droppedFiles.length > 0) {
        // Add only 1 file since we're adding to existing
        var filesToAdd = [droppedFiles[0]]

        // Try to set files on input element (with browser compatibility fallback)
        setInputFiles($('#file-input')[0], filesToAdd)

        handleFileSelect(true)
        StepperState.isAddingFiles = false // reset after handling

        // Show warning if more than 1 file was dropped
        if (droppedFiles.length > 1) {
          showNotification(
            t('only_one_additional')
          )
        }
      }
    })

    // Upload mode tabs
    $('.upload-mode-tab').on('click', function () {
      var mode = $(this).data('upload-mode')
      switchUploadMode(mode)
    })

    // File path input
    $('#import-file-path').on('input', debounce(function () {
      resetValidationState()
      updateValidateButtonState()
    }, CONSTANTS.DEBOUNCE_DELAY))

    // Demo scenarios (for testing)
    if ($('#stepper-state').data('demo-scenarios-enabled')) {
      $('.step-circle').on('dblclick', function () {
        var $panel = $('.demo-scenarios')
        $panel.toggle()
        if ($panel.is(':visible')) {
          // Prefetch scenarios data
          loadDemoScenariosData().catch(function () {
            // Error already handled in loadDemoScenariosData
          })
        }
      })

      $('.scenario-btn').on('click', function () {
        var scenario = $(this).data('scenario')
        loadDemoScenario(scenario)
        $('.demo-scenarios').hide()
      })
    }

    // Start over
    $('.start-over-nav-btn').on('click', function () {
      startOver()
    })

    // Validate button (one per tab; only the active one is visible)
    $('#validate-upload-btn, #validate-path-btn').on('click', function () {
      validateFiles()
    })

    // Warnings acknowledgment
    $('#warnings-acked').on('change', function () {
      StepperState.warningsAcked = $(this).is(':checked')
      updateStepNavigation()
    })

    // Step navigation - next step
    $('.step-next-btn').on('click', function () {
      var nextStep = parseInt($(this).data('next-step'))
      goToStep(nextStep)
    })

    // Step navigation - previous step
    $('.step-prev-btn').on('click', function () {
      var prevStep = parseInt($(this).data('prev-step'))
      goToStep(prevStep)
    })

    // Form submission
    $('#bulk-import-stepper-form').on('submit', function (e) {
      e.preventDefault()
      handleImportSubmit()
    })

    // Start another import
    $('#start-another-import').on('click', function () {
      location.reload()
    })

    // Settings form changes
    $('#importer_name').on('input', debounce(function () {
      StepperState.settings.name = $(this).val()
      updateStepNavigation()
    }, CONSTANTS.DEBOUNCE_DELAY))

    // Admin set selection change
    $('#importer-admin-set').on('change', function () {
      StepperState.adminSetId = $(this).val()
      StepperState.settings.adminSetName = $(this).find('option:selected').text()
      resetValidationState()
      updateStepNavigation()
      updateDownloadTemplateLink()
      // Update validate button state since admin set is required for validation
      if (StepperState.uploadMode === 'file_path' || StepperState.uploadedFiles.length > 0) {
        updateValidateButtonState()
      }
    })

    // Rights statement selection change
    $('select[name="importer[parser_fields][rights_statement]"]').on('change', function () {
      StepperState.settings.rightsStatement = $(this).find('option:selected').text().trim()
      // Clear if "None" was selected
      if (!$(this).val()) {
        StepperState.settings.rightsStatement = ''
      }
      updateStepNavigation()
    })

    $('#bulkrax_importer_limit').on('input', debounce(function () {
      StepperState.settings.limit = $(this).val()
    }, CONSTANTS.DEBOUNCE_DELAY))

    // Remove file button (delegated to parent since rows are dynamic)
    $('.uploaded-files-container').on('click', '.file-remove-btn', function () {
      var $row = $(this).closest('.file-row')
      var fileId = $row.data('file-id')

      var fileEntry = StepperState.uploadedFiles.find(function (f) { return f.id === fileId })
      if (fileEntry) {
        if (fileEntry.uploadXhr) {
          fileEntry.uploadAbortedByUser = true
          fileEntry.uploadXhr.abort()
          StepperState.uploadsInProgress--
        }
        if (fileEntry.uploadId) {
          $.ajax({ url: CONSTANTS.UPLOAD_URL + fileEntry.uploadId, method: 'DELETE', timeout: CONSTANTS.AJAX_TIMEOUT_SHORT })
        }
      }

      // Remove from uploadedFiles array
      StepperState.uploadedFiles = StepperState.uploadedFiles.filter(
        function (file) { return file.id !== fileId }
      )

      // Remove the row
      $row.remove()
      $('#file-input').val('')

      // Reset validation since files changed
      resetValidationState()
      if (StepperState.uploadedFiles.length === 0) {
        StepperState.skipValidation = false
        $('#skip-validation-checkbox').prop('checked', false)
      }

      // Update upload state and re-render
      updateUploadState()
      renderUploadedFiles()
      updateStepNavigation()
    })

    // Skip validation checkbox
    $('#skip-validation-checkbox').on('change', function () {
      StepperState.skipValidation = $(this).is(':checked')
      updateStepNavigation()
    })

    // Mark events as initialized to prevent rebinding on subsequent page loads
    eventsInitialized = true
  }

  // Bind delegated event handlers for dynamically rendered content
  // These handlers are attached to stable parent containers and use event delegation
  // to handle clicks on child elements. This is more efficient than rebinding handlers
  // every time content is re-rendered.
  function bindDelegatedEvents() {
    // Accordion toggle events - delegated to validation results container
    $('.validation-results').on('click.accordion', '.accordion-header', function () {
      var $item = $(this).closest('.accordion-item')
      var $content = $item.find('.accordion-content')
      var $chevron = $item.find('.accordion-chevron')

      if ($item.hasClass('accordion-open')) {
        $content.slideUp(CONSTANTS.ANIMATION_SPEED)
        $chevron.removeClass('fa-chevron-down').addClass('fa-chevron-right')
        $item.removeClass('accordion-open')
      } else {
        $content.slideDown(CONSTANTS.ANIMATION_SPEED)
        $chevron.removeClass('fa-chevron-right').addClass('fa-chevron-down')
        $item.addClass('accordion-open')
      }
    })

    // Tree toggle events - delegated to import summary container
    function toggleTreeItem($item) {
      var $children = $item.next('.tree-children')
      var $chevron = $item.find('.tree-chevron')

      if ($children.length > 0) {
        var isExpanded = $children.is(':visible')
        if (isExpanded) {
          $children.slideUp(CONSTANTS.ANIMATION_SPEED)
          $chevron.removeClass('fa-chevron-down').addClass('fa-chevron-right')
        } else {
          $children.slideDown(CONSTANTS.ANIMATION_SPEED)
          $chevron.removeClass('fa-chevron-right').addClass('fa-chevron-down')
        }
        $item.attr('aria-expanded', String(!isExpanded))
      }
    }

    $('.import-summary').on('click.tree', '.tree-item', function (e) {
      e.stopPropagation()
      toggleTreeItem($(this))
    })

    // Keyboard support for tree items (Enter/Space to toggle)
    $('.import-summary').on('keydown.tree', '.tree-item[tabindex]', function (e) {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault()
        e.stopPropagation()
        toggleTreeItem($(this))
      }
    })
  }

  // ============================================================================
  // FILE VALIDATION & UTILITIES
  // ============================================================================

  // Check if DataTransfer constructor is available
  function isDataTransferSupported() {
    try {
      return typeof DataTransfer !== 'undefined' && typeof DataTransfer === 'function'
    } catch (e) {
      return false
    }
  }

  // Helper to set files on input element with browser compatibility
  function setInputFiles(inputElement, files) {
    if (isDataTransferSupported()) {
      var dataTransfer = new DataTransfer()
      for (var i = 0; i < files.length; i++) {
        dataTransfer.items.add(files[i])
      }
      inputElement.files = dataTransfer.files
      return true
    } else {
      // Fallback for older browsers: can't set files property
      // Return false to indicate files weren't set on input
      console.warn('DataTransfer not supported - files will be processed from memory')
      return false
    }
  }

  // Get file extension (lowercase)
  function getFileExtension(filename) {
    var lastDot = filename.lastIndexOf('.')
    if (lastDot === -1) return ''
    return filename.substring(lastDot).toLowerCase()
  }

  // Validate file extension
  function isValidFileType(filename) {
    var ext = getFileExtension(filename)
    return CONSTANTS.ALLOWED_EXTENSIONS.indexOf(ext) !== -1
  }

  // Show inline error messages
  function showFileUploadError(messages) {
    var errorContainer = $('#file-upload-errors')
    if (messages && messages.length > 0) {
      var parts = [
        '<div class="alert alert-danger alert-dismissible" role="alert">',
        '<button type="button" class="close" data-dismiss="alert" aria-label="Close">',
        '<span aria-hidden="true">&times;</span>',
        '</button>',
        '<strong><span class="fa fa-exclamation-circle"></span> ' + t('file_upload_error') + '</strong>',
        '<ul class="mb-0 mt-2">'
      ]

      messages.forEach(function (msg) {
        // Escape the message but allow intentional <br> tags for newlines
        var escapedMsg = escapeHtml(msg).replace(/\n/g, '<br>')
        parts.push('<li>' + escapedMsg + '</li>')
      })

      parts.push('</ul>', '</div>')
      errorContainer.html(parts.join('')).show()
    } else {
      errorContainer.hide().html('')
    }
  }

  // Clear file upload errors
  function clearFileUploadError() {
    $('#file-upload-errors').hide().html('')
  }

  // ============================================================================
  // FILE UPLOAD HANDLERS
  // ============================================================================

  // Get tenant/account max file size (bytes) from the page, same source as v1 uploader
  function getMaxFileSize() {
    var val = $('.bulk-import-stepper-container').data('max-file-size')
    if (val == null || val === '') return null
    return parseInt(val, 10) || null
  }

  // Ensures the file picker opens in the correct mode (replace vs add)
  // Ensures an invalid file is not added
  function openMainFilePicker() {
    StepperState.isAddingFiles = false
    $('#file-input').val('')
    $('#file-input').trigger('click')
  }

  // Open the file picker in "add" mode (appends to existing files)
  function openAdditionalFilePicker() {
    StepperState.isAddingFiles = true
    $('#file-input').val('')
    $('#file-input').trigger('click')
  }

  // Handle file selection
  function handleFileSelect(isAddingMore) {
    var files = $('#file-input')[0].files
    if (files.length === 0) return

    var maxFileSizeBytes = getMaxFileSize()

    // If not adding more, abort any in-progress uploads and clean up server-side records
    // before replacing the file list so we don't orphan uploads or desync uploadsInProgress.
    if (!isAddingMore) {
      StepperState.uploadedFiles.forEach(function (f) {
        if (f.uploadXhr) {
          f.uploadAbortedByUser = true
          f.uploadXhr.abort()
        }
        if (f.uploadId) {
          $.ajax({ url: CONSTANTS.UPLOAD_URL + f.uploadId, method: 'DELETE', timeout: CONSTANTS.AJAX_TIMEOUT_SHORT })
        }
      })
      StepperState.uploadsInProgress = 0
      StepperState.uploadedFiles = []
    }

    // Count existing file types
    var existingCounts = StepperState.uploadedFiles.reduce(function (counts, f) {
      if (f.fileType === 'csv' && !f.fromZip) counts.csv++
      if (f.fileType === 'zip') counts.zip++
      return counts
    }, { csv: 0, zip: 0 })
    var existingCsvCount = existingCounts.csv
    var existingZipCount = existingCounts.zip

    var addedFiles = []
    var rejectedFiles = []
    var newEntries = []

    // Process selected files with validation
    for (
      var i = 0;
      i < files.length && StepperState.uploadedFiles.length < CONSTANTS.MAX_FILES;
      i++
    ) {
      var file = files[i]
      var fileName = file.name
      var fileSize = formatFileSize(file.size)

      // Validate file extension first
      if (!isValidFileType(fileName)) {
        rejectedFiles.push({
          name: fileName,
          reason: 'invalid_type',
          extension: getFileExtension(fileName)
        })
        continue
      }

      // Reject empty/zero-byte files to avoid server-side errors
      if (file.size === 0) {
        rejectedFiles.push({ name: fileName, reason: 'file_empty' })
        continue
      }

      // Respect tenant/account file size limit (same as v1 and Hyrax uploader)
      if (maxFileSizeBytes != null && file.size > maxFileSizeBytes) {
        rejectedFiles.push({
          name: fileName,
          reason: 'file_too_large',
          size: file.size,
          limit: maxFileSizeBytes
        })
        continue
      }

      var fileType = fileName.endsWith('.csv') ? 'csv' : 'zip'

      // Check for duplicates
      var isDuplicate = StepperState.uploadedFiles.some(function (f) {
        return f.name === fileName
      })

      if (isDuplicate) {
        rejectedFiles.push({ name: fileName, reason: 'duplicate' })
        continue
      }

      // Validate file type constraints (max 1 CSV, max 1 ZIP)
      if (fileType === 'csv' && existingCsvCount >= 1) {
        rejectedFiles.push({ name: fileName, reason: 'duplicate CSV' })
        continue
      }

      if (fileType === 'zip' && existingZipCount >= 1) {
        rejectedFiles.push({ name: fileName, reason: 'duplicate ZIP' })
        continue
      }

      // Add the file with upload tracking properties
      var fileEntry = {
        id: Date.now() + i,
        name: fileName,
        size: fileSize,
        fileType: fileType,
        fromZip: false,
        file: file,
        uploadId: null,
        uploadProgress: 0,
        uploadComplete: false,
        uploadXhr: null
      }
      StepperState.uploadedFiles.push(fileEntry)
      newEntries.push(fileEntry)

      addedFiles.push(fileName)

      // Update counts
      if (fileType === 'csv') existingCsvCount++
      if (fileType === 'zip') existingZipCount++
    }

    // Show appropriate warnings
    if (rejectedFiles.length > 0) {
      var messages = []

      var categorized = rejectedFiles.reduce(function (acc, f) {
        if (f.reason === 'invalid_type') acc.invalidTypes.push(f)
        else if (f.reason === 'file_empty') acc.fileEmpty.push(f)
        else if (f.reason === 'file_too_large') acc.fileTooLarge.push(f)
        else if (f.reason === 'duplicate CSV') acc.duplicateCsv.push(f)
        else if (f.reason === 'duplicate ZIP') acc.duplicateZip.push(f)
        else if (f.reason === 'duplicate') acc.duplicates.push(f)
        return acc
      }, { invalidTypes: [], fileEmpty: [], fileTooLarge: [], duplicateCsv: [], duplicateZip: [], duplicates: [] })

      // Handle invalid file types FIRST
      if (categorized.invalidTypes.length > 0) {
        messages.push(
          t('invalid_format') + '\n' +
          t('rejected_files') + '\n• ' +
          categorized.invalidTypes.map(function (f) {
            return f.name + ' (' + (f.extension || t('no_extension')) + ')'
          }).join('\n• ')
        )
      }

      if (categorized.fileEmpty.length > 0) {
        messages.push(
          'Empty files (0 bytes) are not allowed.\n' +
          'The following files were rejected:\n• ' +
          categorized.fileEmpty.map(function (f) { return f.name }).join('\n• ')
        )
      }
      if (categorized.fileTooLarge.length > 0) {
        var limitMb = categorized.fileTooLarge[0].limit / (1024 * 1024)
        messages.push(
          'File size exceeds the maximum allowed (' + Math.round(limitMb) + ' MB per file).\n' +
          'The following files were rejected:\n• ' +
          categorized.fileTooLarge.map(function (f) {
            return f.name + ' (' + formatFileSize(f.size) + ')'
          }).join('\n• ')
        )
      }

      if (categorized.duplicateCsv.length > 0) {
        messages.push(
          t('csv_limit') + '\n• ' +
          categorized.duplicateCsv
            .map(function (f) {
              return f.name
            })
            .join('\n• ')
        )
      }
      if (categorized.duplicateZip.length > 0) {
        messages.push(
          t('zip_limit') + '\n• ' +
          categorized.duplicateZip
            .map(function (f) {
              return f.name
            })
            .join('\n• ')
        )
      }
      if (categorized.duplicates.length > 0) {
        messages.push(
          t('already_uploaded') + '\n• ' +
          categorized.duplicates
            .map(function (f) {
              return f.name
            })
            .join('\n• ')
        )
      }
      if (
        StepperState.uploadedFiles.length >= CONSTANTS.MAX_FILES &&
        files.length > addedFiles.length + rejectedFiles.length
      ) {
        messages.push(t('max_files', { count: CONSTANTS.MAX_FILES }))
      }

      showFileUploadError(messages)
    } else if (files.length > addedFiles.length) {
      showFileUploadError([
        t('max_files_added', { count: CONSTANTS.MAX_FILES, added: addedFiles.length })
      ])
    } else {
      clearFileUploadError()
    }

    // Reset validation since files changed
    if (addedFiles.length > 0) {
      resetValidationState()
    }

    updateUploadState()
    renderUploadedFiles()

    // Start chunked uploads for newly added files
    newEntries.forEach(function (entry) {
      if (entry.file) {
        uploadFileChunked(entry)
      }
    })
  }

  // ============================================================================
  // DEMO SCENARIOS
  // ============================================================================

  var demoScenariosRequest = null

  // Fetch and cache demo scenarios JSON from server
  function loadDemoScenariosData() {
    // Return cached data as resolved promise
    if (StepperState.demoScenariosData) {
      return Promise.resolve(StepperState.demoScenariosData)
    }

    // Return existing promise if request is already in-flight
    if (demoScenariosRequest) {
      return demoScenariosRequest
    }

    demoScenariosRequest = $.ajax({
      url: CONSTANTS.ENDPOINTS.DEMO_SCENARIOS,
      method: 'GET',
      dataType: 'json',
      timeout: CONSTANTS.AJAX_TIMEOUT_SHORT
    })
      .then(function (data) {
        StepperState.demoScenariosData = data
        demoScenariosRequest = null // Clear in-flight tracker
        return data
      })
      .catch(function (xhr) {
        demoScenariosRequest = null // Clear in-flight tracker on error

        var status = xhr.statusText || 'error'
        var errorMsg = t('demo_load_failed')

        if (status === 'timeout') {
          errorMsg = t('demo_timeout')
        } else if (xhr.status === 0) {
          errorMsg = t('demo_network_error')
        } else if (xhr.status >= 500) {
          errorMsg = t('demo_server_error')
        }

        console.warn(errorMsg, {
          status: status,
          error: xhr.statusText,
          statusCode: xhr.status
        })
        showNotification(errorMsg, 'error')

        // Re-throw to allow caller to handle
        throw new Error(errorMsg)
      })

    return demoScenariosRequest
  }

  // Load demo scenario from cached JSON
  function loadDemoScenario(scenario) {
    resetUploadState()

    loadDemoScenariosData()
      .then(function (data) {
        if (!data || !data.scenarios || !data.scenarios[scenario]) {
          console.warn('Demo scenario not found:', scenario)
          return
        }

        StepperState.uploadedFiles = data.scenarios[scenario].files
        StepperState.demoScenario = scenario
        updateUploadState()
        renderUploadedFiles()
      })
      .catch(function (error) {
        // Error already handled and displayed in loadDemoScenariosData
        console.error('Failed to load demo scenario:', error)
      })
  }

  // ============================================================================
  // CHUNKED FILE UPLOAD (to Hyrax /uploads/ endpoint)
  // ============================================================================

  function uploadFileChunked(fileEntry) {
    var file = fileEntry.file
    if (!file) return

    StepperState.uploadsInProgress++
    fileEntry.uploadProgress = 0
    fileEntry.uploadComplete = false
    fileEntry.uploadId = null
    fileEntry.uploadAbortedByUser = false

    updateValidateButtonState()
    renderUploadedFiles()

    var chunkSize = CONSTANTS.CHUNK_SIZE
    var totalSize = file.size
    var offset = 0

    function sendNextChunk() {
      if (offset >= totalSize) {
        fileEntry.uploadComplete = true
        fileEntry.uploadProgress = 100
        StepperState.uploadsInProgress--
        updateValidateButtonState()
        renderUploadedFiles()
        return Promise.resolve()
      }

      var end = Math.min(offset + chunkSize, totalSize)
      var isFirstChunk = (offset === 0)
      var chunk = file.slice(offset, end)

      var formData = new FormData()
      formData.append('files[]', chunk, file.name)

      var headers = {}
      if (!isFirstChunk) {
        formData.append('id', fileEntry.uploadId)
        headers['Content-Range'] = 'bytes ' + offset + '-' + (end - 1) + '/' + totalSize
      }

      var currentOffset = offset

      return new Promise(function (resolve, reject) {
        var ajaxOptions = {
          url: CONSTANTS.UPLOAD_URL,
          method: 'POST',
          data: formData,
          processData: false,
          contentType: false,
          dataType: 'json',
          timeout: 0,
          xhr: function () {
            var xhr = new XMLHttpRequest()
            xhr.upload.addEventListener('progress', function (e) {
              if (e.lengthComputable) {
                var chunkLoaded = currentOffset + e.loaded
                var percent = Math.round((chunkLoaded / totalSize) * 100)
                fileEntry.uploadProgress = Math.min(percent, 99)
                renderUploadProgress(fileEntry)
              }
            })
            return xhr
          }
        }

        if (Object.keys(headers).length > 0) {
          ajaxOptions.headers = headers
        }

        var jqXhr = $.ajax(ajaxOptions)
        fileEntry.uploadXhr = jqXhr
        jqXhr
          .then(function (result) {
            if (isFirstChunk && result.files && result.files[0]) {
              fileEntry.uploadId = result.files[0].id
            }
            offset = end
            fileEntry.uploadXhr = null
            resolve()
          })
          .catch(function (xhr) {
            fileEntry.uploadXhr = null
            reject(new Error(xhr.statusText || 'Upload failed'))
          })
      }).then(sendNextChunk)
    }

    sendNextChunk().catch(function (error) {
      if (!fileEntry.uploadAbortedByUser) {
        StepperState.uploadsInProgress--
      }
      fileEntry.uploadAbortedByUser = false
      if (fileEntry.uploadId) {
        $.ajax({ url: CONSTANTS.UPLOAD_URL + fileEntry.uploadId, method: 'DELETE', timeout: CONSTANTS.AJAX_TIMEOUT_SHORT })
      }
      StepperState.uploadedFiles = StepperState.uploadedFiles.filter(function (f) {
        return f !== fileEntry
      })
      updateUploadState()
      updateValidateButtonState()
      renderUploadedFiles()
      if (error.message !== 'abort') {
        showNotification('Upload failed for ' + file.name + ': ' + (error.message || 'Unknown error'), 'error')
      }
    })
  }

  function renderUploadProgress(fileEntry) {
    var $row = $('.file-row[data-file-id="' + fileEntry.id + '"]')
    if ($row.length) {
      var pct = fileEntry.uploadProgress || 0
      $row.find('.upload-progress-bar').css('width', pct + '%')
      $row.find('.upload-progress-label').text('Uploading… ' + pct + '%')
    }
  }

  // ============================================================================
  // UPLOAD STATE MANAGEMENT
  // ============================================================================

  // Update upload state based on files
  function updateUploadState() {
    var files = StepperState.uploadedFiles
    if (files.length === 0) {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.EMPTY
      return
    }

    var fileFlags = files.reduce(function (flags, f) {
      if (f.fileType === 'csv' && !f.fromZip) flags.hasStandaloneCsv = true
      if (f.fileType === 'zip') flags.hasZip = true
      if (f.fileType === 'csv' && f.fromZip) flags.hasCsvInZip = true
      return flags
    }, { hasStandaloneCsv: false, hasZip: false, hasCsvInZip: false })

    var hasStandaloneCsv = fileFlags.hasStandaloneCsv
    var hasZip = fileFlags.hasZip
    var hasCsvInZip = fileFlags.hasCsvInZip

    if (hasZip && hasCsvInZip && !hasStandaloneCsv) {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.ZIP_WITH_CSV
    } else if (hasZip && !hasCsvInZip && !hasStandaloneCsv) {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.ZIP_FILES_ONLY
    } else if (hasStandaloneCsv && hasZip) {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.CSV_AND_ZIP
    } else if (hasStandaloneCsv && !hasZip) {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.CSV_ONLY
    } else {
      StepperState.uploadState = CONSTANTS.UPLOAD_STATES.EMPTY
    }
  }

  // Switch between upload and file path modes
  function switchUploadMode(mode) {
    if (mode === StepperState.uploadMode) return

    StepperState.uploadMode = mode

    // Toggle active tab
    $('.upload-mode-tab').removeClass('active')
    $('.upload-mode-tab[data-upload-mode="' + mode + '"]').addClass('active')
    $('.upload-mode-tab').attr('aria-selected', 'false')
    $('.upload-mode-tab[data-upload-mode="' + mode + '"]').attr('aria-selected', 'true')

    if (mode === 'file_path') {
      // Hide upload-related elements, show file path panel
      $('.upload-zone-empty').hide()
      $('.uploaded-files-container').hide()
      $('.add-another-dropzone').hide()
      $('.file-path-panel').show()
      $('#validate-upload-btn').hide()
      $('#validate-path-btn').show()
    } else {
      // Hide file path panel, restore upload state
      $('.file-path-panel').hide()
      $('#validate-path-btn').hide()
      $('#validate-upload-btn').show()
      renderUploadedFiles()
    }

    // Reset validation when switching modes
    resetValidationState()
    updateValidateButtonState()
  }

  // Reset validation state and restore button text (called when inputs change)
  function resetValidationState() {
    if (!StepperState.validated) return

    StepperState.validated = false
    StepperState.validationData = null
    StepperState.warningsAcked = false
    $('#warnings-acked').prop('checked', false)
    $('.validation-results').hide()
    $('.warning-acknowledgment').hide()
    $('#validate-upload-btn').html('<span class="fa fa-file-text"></span> ' + t('validate_upload'))
    $('#validate-path-btn').html('<span class="fa fa-file-text"></span> ' + t('validate_path'))
    renderUploadedFiles()
    updateStepNavigation()
  }

  // Update validate button enabled state based on current upload mode
  function updateValidateButtonState() {
    var $adminSetSelect = $('#importer-admin-set')
    var adminSetValue = $adminSetSelect.val() || StepperState.adminSetId
    var hasAdminSet = adminSetValue && adminSetValue.length > 0

    var canValidate = false

    if (StepperState.uploadMode === 'file_path') {
      var filePath = $('#import-file-path').val() || ''
      canValidate = filePath.trim().length > 0 && hasAdminSet
    } else {
      var fileCheck = StepperState.uploadedFiles.reduce(function (check, f) {
        if (f.fileType === 'csv') check.hasCsv = true
        if (f.fileType === 'zip') check.hasZip = true
        return check
      }, { hasCsv: false, hasZip: false })
      canValidate = (fileCheck.hasCsv || fileCheck.hasZip) && hasAdminSet && !StepperState.validated && StepperState.uploadsInProgress === 0
    }

    var $validateBtn = StepperState.uploadMode === 'file_path' ? $('#validate-path-btn') : $('#validate-upload-btn')
    $validateBtn.prop('disabled', !canValidate)
    if (canValidate || StepperState.skipValidation) {
      $('.skip-validation-label').show()
    } else {
      $('.skip-validation-label').hide()
    }
  }

  // Render uploaded files
  function renderUploadedFiles() {
    // Ensure admin set state is captured (handles timing issues)
    // Always refresh from DOM to ensure we have the current value
    var $adminSetSelect = $('#importer-admin-set')
    if ($adminSetSelect.length && $adminSetSelect.val()) {
      StepperState.adminSetId = $adminSetSelect.val()
      StepperState.adminSetName = $adminSetSelect.find('option:selected').text()
    }

    var state = StepperState.uploadState
    var files = StepperState.uploadedFiles

    // Don't manipulate upload DOM elements when in file path mode
    if (StepperState.uploadMode === 'file_path') return

    if (state === CONSTANTS.UPLOAD_STATES.EMPTY) {
      $('.upload-zone-empty').show()
      $('.uploaded-files-container').hide()
      $('.add-another-dropzone').hide()
      updateValidateButtonState()
      return
    }

    $('.upload-zone-empty').hide()
    $('.uploaded-files-container').show()

    var $list = $('.uploaded-files-list')
    $list.empty()

    // Render all uploaded files — only show status icon after validation
    var validationStatus = null
    if (StepperState.validated && StepperState.validationData) {
      var vd = StepperState.validationData
      if (!vd.isValid) {
        validationStatus = 'error'
      } else if (vd.hasWarnings) {
        validationStatus = 'warning'
      } else {
        validationStatus = 'success'
      }
    }
    var fileRows = files.map(function (file) {
      return renderFileRow(file)
    })
    $list.append(fileRows.join(''))

    // Show appropriate info message based on state
    var infoMessage = ''
    if (state === CONSTANTS.UPLOAD_STATES.ZIP_WITH_CSV) {
      infoMessage =
        '<div class="upload-info"><span class="fa fa-info-circle"></span> ' + t('upload_single_package') + '</div>'
    } else if (state === CONSTANTS.UPLOAD_STATES.CSV_ONLY) {
      infoMessage =
        '<div class="upload-info"><span class="fa fa-info-circle"></span> ' + t('upload_csv_only') + '</div>'
    } else if (state === CONSTANTS.UPLOAD_STATES.ZIP_FILES_ONLY) {
      infoMessage =
        '<div class="upload-info"><span class="fa fa-info-circle"></span> ' + t('upload_zip_only') + '</div>'
    } else if (state === CONSTANTS.UPLOAD_STATES.CSV_AND_ZIP) {
      infoMessage =
        '<div class="upload-info"><span class="fa fa-info-circle"></span> ' + t('upload_csv_and_zip') + '</div>'
    }

    $('.upload-info-message').html(infoMessage)

    // Show file count if multiple files
    if (files.length > 1) {
      $('.uploaded-files-header strong').text(
        t('uploaded_files', { count: files.length })
      )
    } else {
      $('.uploaded-files-header strong').text(t('uploaded_file'))
    }

    // Show/hide "Add another file" dropzone based on file count
    if (files.length === 1) {
      $('.add-another-dropzone').show()
    } else {
      $('.add-another-dropzone').hide()
    }

    updateValidateButtonState()
  }

  // Render a single file row
  function renderFileRow(file) {
    var type = file.fileType
    var name = file.name
    var subtitle = file.subtitle || file.size
    // Show progress until all chunks are done (uploadComplete); uploadId is set after the first
    // chunk so it cannot be used here — the progress bar would vanish mid-upload otherwise.
    // Demo entries (no .file) are treated as already complete.
    var isUploading = file.file && !file.uploadComplete
    var verified = !isUploading

    var icon = type === 'csv' ? 'fa-file-text' : 'fa-file-archive-o'
    var iconBg = type === 'csv' ? 'file-icon-csv' : 'file-icon-zip'

    var progress = file.uploadProgress || 0
    var progressBlock = ''
    if (isUploading) {
      progressBlock =
        '<div class="upload-progress-block">' +
        '<div class="upload-progress-label">Uploading… ' + progress + '%</div>' +
        '<div class="upload-progress-bar-container" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="' + progress + '">' +
        '<div class="upload-progress-bar" style="width:' + progress + '%;"></div>' +
        '</div>' +
        '</div>'
    }

    var statusHtml = verified
      ? '<span class="fa fa-check-circle file-verified file-status-success"></span>'
      : ''

    var safeName = escapeHtml(name)
    var safeSubtitle = escapeHtml(subtitle)

    return (
      '<div class="file-row" data-file-id="' + file.id + '">' +
      '<div class="file-row-main">' +
      '<div class="file-info">' +
      '<div class="file-icon ' + iconBg + '"><span class="fa ' + icon + '"></span></div>' +
      '<div class="file-details">' +
      '<div class="file-name">' + safeName + '</div>' +
      '<div class="file-subtitle">' + safeSubtitle + '</div>' +
      '</div>' +
      '</div>' +
      '<div class="file-actions">' +
      statusHtml +
      '<button type="button" class="file-remove-btn" aria-label="' + t('remove_file') + '">' +
      '<span class="fa fa-times"></span>' +
      '</button>' +
      '</div>' +
      '</div>' +
      progressBlock +
      '</div>'
    )
  }

  // Reset upload state
  function resetUploadState() {
    // Abort in-progress uploads and delete server-side files.
    // Mark as user-aborted first so the catch handler doesn't double-decrement uploadsInProgress.
    StepperState.uploadedFiles.forEach(function (f) {
      if (f.uploadXhr) {
        f.uploadAbortedByUser = true
        f.uploadXhr.abort()
      }
      if (f.uploadId) {
        $.ajax({ url: CONSTANTS.UPLOAD_URL + f.uploadId, method: 'DELETE', timeout: CONSTANTS.AJAX_TIMEOUT_SHORT })
      }
    })
    StepperState.uploadsInProgress = 0

    StepperState.uploadedFiles = []
    StepperState.uploadState = CONSTANTS.UPLOAD_STATES.EMPTY
    StepperState.validated = false
    StepperState.validationData = null
    StepperState.warningsAcked = false
    StepperState.skipValidation = false
    StepperState.demoScenario = null
    $('#file-input').val('')
    $('#import-file-path').val('')
    $('.validation-results').hide()
    $('.warning-acknowledgment').hide()
    $('#warnings-acked').prop('checked', false)
    clearFileUploadError()

    // Clear all notifications
    $('#upload-notifications').empty()

    // Reset skip validation checkbox and label
    $('#skip-validation-checkbox').prop('checked', false)
    // Visibility is controlled by updateValidateButtonState

    // Reset both validate buttons to original state
    $('#validate-upload-btn')
      .prop('disabled', true)
      .html('<span class="fa fa-file-text"></span> ' + t('validate_upload'))
    $('#validate-path-btn')
      .prop('disabled', true)
      .html('<span class="fa fa-file-text"></span> ' + t('validate_path'))

    renderUploadedFiles()
    updateStepNavigation()
  }

  // Full reset: clear everything and return to step 1
  function startOver() {
    // Reset files and validation
    resetUploadState()

    // Reset upload mode to default "upload" tab
    StepperState.uploadMode = 'upload'
    $('.upload-mode-tab').removeClass('active')
    $('.upload-mode-tab[data-upload-mode="upload"]').addClass('active')
    $('.uploaded-files-container').hide()
    $('.file-path-panel').hide()
    $('#validate-path-btn').hide()
    $('#validate-upload-btn').show()

    // Reset admin set to default
    var $adminSetSelect = $('#importer-admin-set')
    var defaultAdminSet = $adminSetSelect.find('option').filter(function () {
      return $(this).text().indexOf('Default') !== -1
    }).val() || ''
    $adminSetSelect.val(defaultAdminSet)
    StepperState.adminSetId = defaultAdminSet
    StepperState.adminSetName = $adminSetSelect.find('option:selected').text()

    // Reset settings
    setDefaultImportName()
    StepperState.settings.visibility = 'open'
    $('.visibility-card').removeClass('active')
    $('.visibility-card[data-visibility="open"]').addClass('active')
    $('input[name="importer[parser_fields][visibility]"][value="open"]').prop('checked', true)
    $('select[name="importer[parser_fields][rights_statement]"]').val('')
    StepperState.settings.rightsStatement = ''
    $('#bulkrax_importer_limit').val('')
    StepperState.settings.limit = ''
    $('input[name="importer[parser_fields][override_rights_statement]"]').prop('checked', false)

    // Clear review step warnings from previous run
    $('.review-errors-list').empty()
    $('.review-errors').hide()
    $('.review-warnings-list').empty()
    $('.review-warnings').hide()
    $('.large-import-warning').hide()

    // Navigate to step 1
    goToStep(1)
  }

  // ============================================================================
  // VALIDATION
  // ============================================================================

  // Perform validation API call with uploaded file IDs
  function performValidation(data) {
    return $.ajax({
      url: CONSTANTS.ENDPOINTS.VALIDATE,
      method: 'POST',
      data: data,
      timeout: CONSTANTS.AJAX_TIMEOUT_LONG
    })
  }

  function performFilePathValidation(filePath) {
    return $.ajax({
      url: CONSTANTS.ENDPOINTS.VALIDATE,
      method: 'POST',
      data: {
        importer: {
          parser_fields: {
            import_file_path: filePath
          },
          admin_set_id: StepperState.adminSetId
        },
        locale: $('input[name="locale"]').val()
      },
      timeout: CONSTANTS.AJAX_TIMEOUT_LONG
    })
  }

  // Simulate validation for demo scenarios
  function performMockValidation() {
    return new Promise(function (resolve, reject) {
      setTimeout(function () {
        var mockData = getMockValidationData()
        if (!mockData) {
          reject(new Error(t('demo_data_not_loaded')))
          return
        }
        resolve(mockData)
      }, CONSTANTS.VALIDATION_DELAY)
    })
  }

  // Update UI after successful validation
  function handleValidationSuccess(data, $btn) {
    var normalized = normalizeValidationData(data)
    StepperState.validated = true
    StepperState.validationData = normalized

    try {
      renderValidationResults(normalized)
      renderUploadedFiles()
      $('.skip-validation-label').hide()
      $btn.html('<span class="fa fa-check-circle"></span> ' + t('validated'))
      updateStepNavigation()
    } catch (e) {
      console.error('Validation results render issue:', e)
      throw new Error(t('render_error'))
    }
  }

  // Update UI after validation error
  function handleValidationError(error, $btn) {
    var xhr = error
    var status = xhr.statusText || 'error'
    var errorMsg = t('validation_failed')

    // Handle specific error cases
    if (status === 'timeout') {
      errorMsg = t('validation_timeout')
    } else if (xhr.status === 0) {
      errorMsg = t('network_error')
    } else if (xhr.status === 413) {
      errorMsg = t('files_too_large')
    } else if (xhr.status === 422) {
      errorMsg = xhr.responseJSON && xhr.responseJSON.error
        ? xhr.responseJSON.error
        : t('invalid_file_format')
    } else if (xhr.status >= 500) {
      errorMsg = t('server_error')
    } else if (xhr.responseJSON && xhr.responseJSON.error) {
      errorMsg = xhr.responseJSON.error
    }

    console.error('Validation error:', {
      status: status,
      error: xhr.statusText,
      statusCode: xhr.status,
      response: xhr.responseJSON
    })

    showNotification(errorMsg, 'error')

    // Reset button state
    var resetLabel = $btn.attr('id') === 'validate-path-btn'
      ? '<span class="fa fa-file-text"></span> ' + t('validate_path')
      : '<span class="fa fa-file-text"></span> ' + t('validate_upload')
    $btn
      .prop('disabled', false)
      .html(resetLabel)

    // Reset validation state on error
    StepperState.validated = false
    StepperState.validationData = null
  }

  // Validate files (AJAX call to backend)
  function validateFiles() {
    var $btn = StepperState.uploadMode === 'file_path' ? $('#validate-path-btn') : $('#validate-upload-btn')
    $btn
      .prop('disabled', true)
      .html('<span class="fa fa-spinner fa-spin"></span> ' + t('validating'))

    // Uncheck "Skip validation" since the user is actively validating
    if (StepperState.skipValidation) {
      StepperState.skipValidation = false
      $('#skip-validation-checkbox').prop('checked', false)
    }

    // Check if we're in demo mode (no real uploaded files on server)
    var hasRealFiles = StepperState.uploadedFiles.some(function (f) { return f.uploadId })
    var filePathValue = $('#import-file-path').val().trim()
    var hasFilePath = filePathValue.length > 0
    var useMockData = !hasRealFiles && !hasFilePath

    // Send uploaded file IDs instead of raw file bytes
    var validationData
    if (!useMockData && !hasFilePath) {
      validationData = {
        uploaded_files: StepperState.uploadedFiles
          .filter(function (f) { return f.uploadId })
          .map(function (f) { return f.uploadId }),
        importer: {
          admin_set_id: StepperState.adminSetId
        },
        locale: $('input[name="locale"]').val()
      }
    }

    // Choose validation method based on the active upload mode tab.
    // Each tab is validated independently — no cross-tab priority.
    var validationPromise
    if (StepperState.uploadMode === 'file_path') {
      var filePathValue = $('#import-file-path').val().trim()
      validationPromise = performFilePathValidation(filePathValue)
    } else {
      if (useMockData) {
        validationPromise = performMockValidation()
      } else if (validationData) {
        validationPromise = performValidation(validationData)
      } else {
        showNotification('No files to validate. Upload files or enter an import path.', 'warning')
        $btn.prop('disabled', false).html($btn.attr('id') === 'validate-path-btn'
          ? '<span class="fa fa-file-text"></span> Validate Files from Import Path'
          : '<span class="fa fa-file-text"></span> Validate Files from Upload')
        return
      }
    }

    // Handle validation result
    validationPromise
      .then(function (data) {
        handleValidationSuccess(data, $btn)
      })
      .catch(function (error) {
        handleValidationError(error, $btn)
      })
  }

  // Helper: Determine if validation data indicates valid state
  function determineIsValid(data) {
    // Check both camelCase and snake_case property names
    var isValidValue = normalizeBoolean(data.isValid != null ? data.isValid : data.is_valid)

    // If explicitly set to true or false, use that value
    if (isValidValue !== null) {
      return isValidValue
    }

    // Fallback: If we have row data but no explicit validity flag,
    // assume valid (backend processed without marking as invalid)
    var hasRowData = data.rowCount != null || data.row_count != null
    return hasRowData
  }

  // Helper: Determine if validation has warnings
  function determineHasWarnings(data) {
    var hasWarningsValue = normalizeBoolean(
      data.hasWarnings != null ? data.hasWarnings : data.has_warnings
    )
    return hasWarningsValue === true
  }

  function normalizeValidationData(data) {
    if (!data) return data
    return {
      collections: data.collections,
      works: data.works,
      fileSets: data.fileSets || data.file_sets,
      totalItems: data.totalItems != null ? data.totalItems : data.total_items,
      headers: data.headers,
      missingRequired: data.missingRequired || data.missing_required,
      unrecognized: data.unrecognized,
      rowCount: data.rowCount != null ? data.rowCount : data.row_count,
      isValid: determineIsValid(data),
      hasWarnings: determineHasWarnings(data),
      messages: data.messages,
      validationErrorsCacheKey: data.validationErrorsCacheKey || null
    }
  }

  // Normalize childrenIds into parentIds and build a hierarchy lookup map.
  // This converts parent-declares-children relationships into the canonical
  // child-declares-parent form, then pre-computes a map for O(1) hierarchy lookups.

  function normalizeRelationships(data) {
    var allItems = data.collections.concat(data.works)

    // Build id -> item lookup
    var itemMap = {}
    allItems.forEach(function (item) {
      if (!item.parentIds) { item.parentIds = [] }
      itemMap[item.id] = item
    })

    allItems.forEach(function (item) {
      if (item.childIds && item.childIds.length > 0) {
        item.childIds.forEach(function (childId) {
          var child = itemMap[childId]
          if (child) {
            if (child.parentIds.indexOf(item.id) === -1) {
              child.parentIds.push(item.id)
            }
          }
        })
      }
    })

    // Inject stub nodes for existing-record relationships so the tree can
    // render them as children/parents even though they are not in the CSV.
    allItems.forEach(function (item) {
      // existingChildIds → the item in the CSV has a child that lives in the repo
      ;(item.existingChildIds || []).forEach(function (childId) {
        if (!itemMap[childId]) {
          itemMap[childId] = { id: childId, title: childId, type: 'existing', parentIds: [], existing: true }
        }
        if (itemMap[childId].parentIds.indexOf(item.id) === -1) {
          itemMap[childId].parentIds.push(item.id)
        }
      })
      // existingParentIds → the item in the CSV has a parent that lives in the repo
      ;(item.existingParentIds || []).forEach(function (parentId) {
        if (!itemMap[parentId]) {
          itemMap[parentId] = { id: parentId, title: parentId, type: 'existing', parentIds: [], existing: true }
        }
        if (item.parentIds.indexOf(parentId) === -1) {
          item.parentIds.push(parentId)
        }
      })
    })

    // Build hierarchy lookup map from normalized parentIds (including existing stubs)
    var hierarchyMap = {}
    Object.keys(itemMap).forEach(function (id) {
      var item = itemMap[id]
      item.parentIds.forEach(function (parentId) {
        if (!hierarchyMap[parentId]) { hierarchyMap[parentId] = [] }
        if (hierarchyMap[parentId].indexOf(item) === -1) {
          hierarchyMap[parentId].push(item)
        }
      })
    })

    return hierarchyMap
  }

  // ============================================================================
  // VALIDATION RESULTS RENDERING
  // ============================================================================

  // Render validation results
  function renderValidationResults(data) {
    $('.validation-results').show()

    // Normalize childrenIds -> parentIds and build hierarchy lookup map
    var hierarchyMap = normalizeRelationships(data)

    // Import size gauge
    renderImportSizeGauge(data.totalItems)

    // Validation status accordion
    renderValidationAccordions(data)

    // Import summary
    renderImportSummary(data, hierarchyMap)

    // Warning/error acknowledgment
    if (data.hasWarnings || !data.isValid) {
      $('.warning-acknowledgment').show()
    }

    // Download errors button
    if (data.validationErrorsCacheKey) {
      var locale = $('input[name="locale"]').val()
      var downloadUrl =
        CONSTANTS.ENDPOINTS.DOWNLOAD_VALIDATION_ERRORS +
        '?key=' + encodeURIComponent(data.validationErrorsCacheKey) +
        (locale ? '&locale=' + encodeURIComponent(locale) : '')
      var $btn = $(
        '<a class="btn btn-outline-secondary btn-sm mt-2" href="' +
          downloadUrl +
          '" download>' +
          '<i class="fa fa-download"></i> ' +
          t('download_validation_errors_csv') +
          '</a>'
      )
      $('.validation-results .download-errors-container').remove()
      $('.validation-results').append($('<div class="download-errors-container mt-2"></div>').append($btn))
    } else {
      $('.validation-results .download-errors-container').remove()
    }
  }

  // Render import size gauge
  function renderImportSizeGauge(count) {
    var pct, color, zone, msg, cardClass

    if (count <= CONSTANTS.IMPORT_SIZE_OPTIMAL) {
      pct = (count / CONSTANTS.IMPORT_SIZE_OPTIMAL) * 33
      color = 'gauge-marker-optimal'
      zone = t('gauge_optimal')
      msg = t('gauge_optimal_msg')
      cardClass = 'gauge-card-optimal'
    } else if (count <= CONSTANTS.IMPORT_SIZE_MODERATE) {
      pct = 33 + ((count - CONSTANTS.IMPORT_SIZE_OPTIMAL) / (CONSTANTS.IMPORT_SIZE_MODERATE - CONSTANTS.IMPORT_SIZE_OPTIMAL)) * 33
      color = 'gauge-marker-moderate'
      zone = t('gauge_moderate')
      msg = t('gauge_moderate_msg')
      cardClass = 'gauge-card-moderate'
    } else {
      pct = Math.min(66 + ((count - CONSTANTS.IMPORT_SIZE_MODERATE) / CONSTANTS.IMPORT_SIZE_MODERATE) * 34, 100)
      color = 'gauge-marker-large'
      zone = t('gauge_large')
      msg = t('gauge_large_msg', { limit: CONSTANTS.IMPORT_SIZE_OPTIMAL })
      cardClass = 'gauge-card-large'
    }

    var html =
      '<div class="gauge-card ' +
      cardClass +
      '">' +
      '<div class="gauge-header">' +
      '<span>' +
      t('gauge_import_size', { count: count }) +
      '</span>' +
      '<span class="gauge-zone">' +
      zone +
      '</span>' +
      '</div>' +
      '<div class="gauge-track">' +
      '<div class="gauge-segment gauge-segment-optimal"></div>' +
      '<div class="gauge-segment gauge-segment-moderate"></div>' +
      '<div class="gauge-segment gauge-segment-large"></div>' +
      '<div class="gauge-marker ' +
      color +
      '" style="left: ' +
      pct +
      '%"></div>' +
      '</div>' +
      '<div class="gauge-labels">' +
      '<span>0</span><span>' + CONSTANTS.IMPORT_SIZE_OPTIMAL + '</span><span>' + CONSTANTS.IMPORT_SIZE_MODERATE + '</span><span>' + CONSTANTS.IMPORT_SIZE_LARGE + '+</span>' +
      '</div>' +
      '<p class="gauge-message text-muted small">' +
      msg +
      '</p>' +
      '</div>'

    $('.import-size-gauge').html(html)
  }

  // Group items by model for missing required fields
  function groupItemsByModel(items) {
    var grouped = {}
    items.forEach(function (item) {
      var modelName = item.model || 'Unknown'
      if (!grouped[modelName]) {
        grouped[modelName] = []
      }
      grouped[modelName].push(item.field)
    })
    return grouped
  }

  // Render missing required fields grouped by model. Group count capped at
  // CONSTANTS.MAX_ISSUE_ITEMS so we never show a partial group.
  function renderMissingRequiredFields(items) {
    var groupedByModel = groupItemsByModel(items)
    var modelNames = Object.keys(groupedByModel).slice(0, CONSTANTS.MAX_ISSUE_ITEMS)
    var parts = []

    modelNames.forEach(function (modelName) {
      parts.push('<div class="missing-field-group">')
      parts.push('<strong class="missing-field-model">' + modelName + '</strong>')
      parts.push('<ul>')

      // Map fields to list items, then join once
      var fieldItems = groupedByModel[modelName].map(function (field) {
        return '<li>• ' + field + '</li>'
      })
      parts.push(fieldItems.join(''))

      parts.push('</ul>')
      parts.push('</div>')
    })

    return parts.join('')
  }

  // Render default issue items (unrecognized fields, file references, etc.).
  // When items carry a `category` (row-level errors/warnings), show up to
  // CONSTANTS.MAX_ISSUE_ITEMS per category so each distinct problem type is
  // represented. Otherwise fall back to a simple slice of the first N items.
  function renderDefaultIssueItems(items) {
    var hasCategories = items.some(function (item) { return item.category })
    var capped = hasCategories ? capItemsPerCategory(items) : items.slice(0, CONSTANTS.MAX_ISSUE_ITEMS)
    var listItems = capped.map(function (item) {
      var msg = item.message ? ' — ' + item.message : ''
      return '<li>• ' + item.field + msg + '</li>'
    })

    return '<ul>' + listItems.join('') + '</ul>'
  }

  // Keep the first CONSTANTS.MAX_ISSUE_ITEMS entries per category, preserving
  // their original order so rows still read top-to-bottom within each category.
  function capItemsPerCategory(items) {
    var counts = {}
    var result = []
    items.forEach(function (item) {
      var cat = item.category || 'uncategorized'
      counts[cat] = (counts[cat] || 0) + 1
      if (counts[cat] <= CONSTANTS.MAX_ISSUE_ITEMS) result.push(item)
    })
    return result
  }

  // Render issue items based on issue type
  function renderIssueItems(issue) {
    var hasModelField = issue.items.some(function (item) { return item.model })

    if (issue.type === 'missing_required_fields' && hasModelField) {
      return renderMissingRequiredFields(issue.items)
    } else {
      return renderDefaultIssueItems(issue.items)
    }
  }

  // Render validation accordions
  function renderValidationAccordions(data) {
    var $wrapper = $('.accordion-wrapper')
    $wrapper.empty()

    // Check if we have the new messages structure
    if (!data.messages || !data.messages.validationStatus) {
      console.error('Invalid validation response: missing messages structure')
      return
    }

    // Main validation status - FROM BACKEND
    var status = data.messages.validationStatus
    var content = '<p>' + status.summary + '</p>'
    if (status.details) {
      content += '<p class="text-muted small">' + status.details + '</p>'
    }

    $wrapper.append(
      createAccordion(
        status.title,
        status.icon,
        status.severity,
        null,
        status.defaultOpen,
        content
      )
    )

    // Render all issues - FROM BACKEND
    // Each issue uses its own severity for independent coloring
    if (data.messages.issues && data.messages.issues.length > 0) {
      data.messages.issues.forEach(function (issue) {
        var issueContent = ''

        if (issue.description) {
          issueContent += '<p>' + issue.description + '</p>'
        }

        if (issue.summary) {
          issueContent += '<p>' + issue.summary + '</p>'
        }

        if (issue.items && issue.items.length > 0) {
          issueContent += renderIssueItems(issue)
        }

        if (issue.details) {
          issueContent += '<p class="small">' + issue.details + '</p>'
        }

        $wrapper.append(
          createAccordion(
            issue.title,
            issue.icon,
            issue.severity,
            countDisplayFor(issue),
            issue.defaultOpen,
            issueContent
          )
        )
      })
    }

  }

  // Build the count badge display for a validation issue accordion.
  // Returns a plain number (or null) normally, or an HTML fragment with a
  // truncation note when the inline list is capped.
  function countDisplayFor(issue) {
    if (issue.count == null) return null
    if (!isIssueTruncated(issue)) return issue.count

    var noteText = t('validation_truncated_note', {
      shown: issueShownCount(issue)
    })
    var tooltip = t('validation_truncated_tooltip')
    return issue.count +
      ' <span class="accordion-count-note" title="' + escapeHtml(tooltip) +
      '" aria-label="' + escapeHtml(tooltip) + '">' +
      escapeHtml(noteText) + '</span>'
  }

  // How many items are actually rendered in the accordion body, mirroring the
  // slicing logic in renderDefaultIssueItems / renderMissingRequiredFields.
  function issueShownCount(issue) {
    var items = issue.items || []
    if (!items.length) return 0

    var hasModelField = issue.type === 'missing_required_fields' &&
      items.some(function (item) { return item.model })
    if (hasModelField) {
      return Math.min(issueDisplayUnitCount(issue), CONSTANTS.MAX_ISSUE_ITEMS)
    }

    var hasCategories = items.some(function (item) { return item.category })
    if (hasCategories) return capItemsPerCategory(items).length

    return Math.min(items.length, CONSTANTS.MAX_ISSUE_ITEMS)
  }

  // Decide whether an issue's rendered item list is capped. Mirrors the
  // slicing logic in renderDefaultIssueItems / renderMissingRequiredFields so
  // the header note only appears when items are actually dropped.
  function isIssueTruncated(issue) {
    var items = issue.items || []
    if (!items.length) return false

    var hasModelField = issue.type === 'missing_required_fields' &&
      items.some(function (item) { return item.model })
    if (hasModelField) return issueDisplayUnitCount(issue) > CONSTANTS.MAX_ISSUE_ITEMS

    var hasCategories = items.some(function (item) { return item.category })
    if (hasCategories) {
      var counts = {}
      for (var i = 0; i < items.length; i++) {
        var cat = items[i].category || 'uncategorized'
        counts[cat] = (counts[cat] || 0) + 1
        if (counts[cat] > CONSTANTS.MAX_ISSUE_ITEMS) return true
      }
      return false
    }

    return items.length > CONSTANTS.MAX_ISSUE_ITEMS
  }

  // Render one review-section (errors or warnings) on Step 3 from a list of
  // validation issues. Each issue gets a breakdown appropriate to its shape:
  // row-level issues group by category, missing_required_fields groups by
  // model, everything else is a flat list of field names.
  function renderReviewIssueSection(issues, sectionSelector, listSelector) {
    if (!issues.length) {
      $(listSelector).empty()
      $(sectionSelector).hide()
      return
    }

    var html = ''
    issues.forEach(function (issue) {
      var label = issue.title
      if (issue.count) { label += ' (' + issue.count + ')' }
      var detail = issue.summary || issue.description || ''
      html += '<p>' + label
      if (detail) { html += ' — ' + detail }
      html += '</p>'

      html += renderReviewIssueBreakdown(issue)
    })
    $(listSelector).html(html)
    $(sectionSelector).show()
  }

  // Pick the right breakdown renderer for an issue on the Step 3 summary.
  function renderReviewIssueBreakdown(issue) {
    var items = issue.items || []
    if (!items.length) return ''

    if (issue.type === 'row_level_errors' || issue.type === 'row_level_warnings') {
      return renderWarningCategoryBreakdown(items)
    }
    if (issue.type === 'missing_required_fields' && items.some(function (i) { return i.model })) {
      return renderMissingRequiredBreakdown(items)
    }
    return renderFieldListBreakdown(items)
  }

  // Missing required fields grouped by model, matching the Step 1 accordion layout.
  function renderMissingRequiredBreakdown(items) {
    var grouped = groupItemsByModel(items)
    var html = '<ul class="review-warning-categories">'
    Object.keys(grouped).forEach(function (modelName) {
      var fields = grouped[modelName].map(escapeHtml).join(', ')
      html += '<li><strong>' + escapeHtml(modelName) + ':</strong> ' + fields + '</li>'
    })
    html += '</ul>'
    return html
  }

  // Flat list of `field — message` entries — used for unrecognized fields,
  // file references, notices. Message provides the context a bare field name
  // lacks (e.g. "No model column found — all rows will be imported as …").
  function renderFieldListBreakdown(items) {
    var html = '<ul class="review-warning-categories">'
    items.forEach(function (item) {
      if (!item || !item.field) return
      var line = escapeHtml(item.field)
      if (item.message) line += ' — ' + escapeHtml(item.message)
      html += '<li>' + line + '</li>'
    })
    html += '</ul>'
    return html
  }

  // Render a bulleted breakdown of row-warning items grouped by category.
  // Used on the Review & Start Import step under "Row Validation Warnings".
  function renderWarningCategoryBreakdown(items) {
    var counts = items.reduce(function (acc, item) {
      var cat = item.category || 'uncategorized'
      acc[cat] = (acc[cat] || 0) + 1
      return acc
    }, {})
    var html = '<ul class="review-warning-categories">'
    Object.keys(counts).forEach(function (cat) {
      html += '<li>' + escapeHtml(warningCategoryLabel(cat)) + ' (' + counts[cat] + ')</li>'
    })
    html += '</ul>'
    return html
  }

  // Localized label for a warning category, with a humanized fallback so a
  // new validator category doesn't produce raw snake_case in the UI.
  function warningCategoryLabel(category) {
    var key = 'warning_category_' + category
    var label = t(key)
    if (label === key) return humanizeCategory(category)
    return label
  }

  function humanizeCategory(category) {
    if (!category) return ''
    return category
      .replace(/_/g, ' ')
      .replace(/\b\w/g, function (c) { return c.toUpperCase() })
  }

  // Count the display units for an issue. For missing-required-fields grouped
  // by model the unit is a model-group; for everything else it's an item.
  function issueDisplayUnitCount(issue) {
    if (!issue.items || !issue.items.length) return 0
    var hasModelField = issue.type === 'missing_required_fields' &&
      issue.items.some(function (item) { return item.model })
    if (!hasModelField) return issue.items.length

    var seen = {}
    var groups = 0
    issue.items.forEach(function (item) {
      var key = item.model || 'Unknown'
      if (!seen[key]) {
        seen[key] = true
        groups += 1
      }
    })
    return groups
  }

  // Create accordion HTML
  function createAccordion(title, icon, variant, count, defaultOpen, content) {
    var variantClass = 'accordion-' + variant
    var openClass = defaultOpen ? 'accordion-open' : ''
    var contentDisplay = defaultOpen ? 'block' : 'none'
    var chevron = defaultOpen ? 'fa-chevron-down' : 'fa-chevron-right'
    var countBadge =
      count !== null ? '<span class="accordion-count">' + count + '</span>' : ''

    return (
      '<div class="accordion-item ' +
      variantClass +
      ' ' +
      openClass +
      '">' +
      '<button type="button" class="accordion-header">' +
      '<div class="accordion-title-bar">' +
      '<span class="fa ' +
      icon +
      ' accordion-status-icon"></span>' +
      '<span>' +
      title +
      '</span>' +
      countBadge +
      '</div>' +
      '<span class="fa ' +
      chevron +
      ' accordion-chevron"></span>' +
      '</button>' +
      '<div class="accordion-content" style="display: ' +
      contentDisplay +
      '">' +
      content +
      '</div>' +
      '</div>'
    )
  }

  // Note: Accordion toggle events are handled via event delegation in bindDelegatedEvents()

  // ============================================================================
  // IMPORT SUMMARY & HIERARCHY
  // ============================================================================

  // Render import summary
  function renderImportSummary(data, hierarchyMap) {
    $('.summary-card-collections .summary-number').text(data.collections.length)
    $('.summary-card-works .summary-number').text(data.works.length)
    $('.summary-card-filesets .summary-number').text(data.fileSets.length)

    // Hierarchy accordions
    var $container = $('.hierarchy-accordions')
    $container.empty()

    // Import hierarchy — collections, nested items, and standalone works in one tree
    var topLevelCollections = data.collections.filter(function (c) {
      return !c.parentIds || c.parentIds.length === 0
    })
    var orphanWorks = data.works.filter(function (w) {
      return !w.parentIds || w.parentIds.length === 0
    })
    // Existing-record stubs that are top-level parents (not themselves children of anything)
    var existingRoots = Object.keys(hierarchyMap)
      .filter(function (id) {
        var allCsvIds = data.collections.concat(data.works).map(function (i) { return i.id })
        return allCsvIds.indexOf(id) === -1
      })
      .map(function (id) {
        return { id: id, title: id, type: 'existing', parentIds: [], existing: true }
      })
    var hierarchyContent =
      '<div class="hierarchy-tree">' +
      existingRoots
        .map(function (e) {
          return renderTreeItem(e, hierarchyMap, 0, new Set())
        })
        .join('') +
      topLevelCollections
        .map(function (c) {
          return renderTreeItem(c, hierarchyMap, 0, new Set())
        })
        .join('') +
      orphanWorks
        .map(function (w) {
          return renderTreeItem(w, hierarchyMap, 0, new Set())
        })
        .join('') +
      '</div>'
    var itemCount = data.collections.length + data.works.length
    $container.append(
      createAccordion(
        t('import_hierarchy'),
        'fa-sitemap',
        'info',
        itemCount,
        false,
        hierarchyContent
      )
    )

  }

  // Render tree item recursively using pre-computed hierarchyMap
  // Guarded with depth limit and circular reference detection
  function renderTreeItem(item, hierarchyMap, depth, visited) {
    depth = depth || 0

    // Limit tree depth to prevent stack overflow
    if (depth >= CONSTANTS.MAX_TREE_DEPTH) {
      console.warn('Max tree depth reached for item:', item.id)
      return '<div class="tree-item tree-truncated" style="padding-left: ' + (depth * 20) + 'px">' +
        '<span class="fa fa-ellipsis-h text-muted"></span>' +
        '<span class="tree-label text-muted"><em>' + t('hierarchy_too_deep', { max: CONSTANTS.MAX_TREE_DEPTH }) + '</em></span>' +
        '</div>'
    }

    // Detect circular references
    if (visited.has(item.id)) {
      console.error('Circular reference detected for item:', item.id)
      return '<div class="tree-item tree-error" style="padding-left: ' + (depth * 20) + 'px">' +
        '<span class="fa fa-exclamation-triangle text-danger"></span>' +
        '<span class="tree-label text-danger"><em>' + t('circular_reference') + '</em></span>' +
        '</div>'
    }

    visited.add(item.id)

    var children = hierarchyMap[item.id] || []
    var hasChildren = children.length > 0
    var isExisting = !!item.existing
    var icon = item.type === 'collection' ? 'fa-folder' : 'fa-file-o'
    var iconColor = isExisting ? 'text-muted' : (item.type === 'collection' ? 'text-primary' : 'text-muted')
    // Hidden chevron still takes up space (via fixed width in CSS) to prevent icon shifting
    var chevronClass = hasChildren ? 'tree-chevron' : 'tree-chevron tree-chevron-hidden'
    var chevron = '<span class="fa fa-chevron-right ' + chevronClass + '"></span>'
    var count = hasChildren
      ? ' <span class="text-muted small">(' + children.length + ')</span>'
      : ''
    var paddingLeft = depth * 20

    // Escape user-provided data
    var safeId = escapeHtml(item.id)
    var safeTitle = escapeHtml(item.title)

    // Make expandable tree items focusable and semantically interactive
    var treeItemAttrs = hasChildren
      ? ' tabindex="0" role="treeitem" aria-expanded="false"'
      : ''

    var existingBadge = isExisting
      ? '<span class="tree-existing-badge" title="' + t('existing_record_title') + '">' +
        t('existing_record_badge') + '</span>'
      : ''

    var html =
      '<div class="tree-item' + (isExisting ? ' tree-item-existing' : '') + '" data-item-id="' +
      safeId +
      '"' + treeItemAttrs + ' style="padding-left: ' +
      paddingLeft +
      'px">' +
      chevron +
      '<span class="fa ' +
      icon +
      ' ' +
      iconColor +
      '"></span>' +
      '<span class="tree-label' + (isExisting ? ' tree-label-existing' : '') + '">' +
      safeTitle +
      '</span>' +
      (item.parentIds && item.parentIds.length > 1
        ? '<span class="tree-shared-badge" title="' +
        t('appears_in_collections', { count: item.parentIds.length }) + '">' +
        '<span class="fa fa-link"></span> ' + t('shared_badge') + '</span>'
        : '') +
      count +
      existingBadge +
      '</div>'

    if (hasChildren) {
      html +=
        '<div class="tree-children" style="display: none;">' +
        children
          .map(function (c) {
            return renderTreeItem(c, hierarchyMap, depth + 1, new Set(visited))
          })
          .join('') +
        '</div>'
    }

    return html
  }

  // Note: Tree toggle events are handled via event delegation in bindDelegatedEvents()

  // ============================================================================
  // SETTINGS & NAVIGATION
  // ============================================================================

  // Initialize visibility cards
  function initVisibilityCards() {
    $('.visibility-card').on('click', function () {
      var visibility = $(this).data('visibility')
      $('.visibility-card').removeClass('active')
      $(this).addClass('active')
      $(this).find('input[type="radio"]').prop('checked', true)
      StepperState.settings.visibility = visibility
    })

    // Set default
    $('.visibility-card[data-visibility="open"]').addClass('active')
  }

  // Set default import name
  function setDefaultImportName() {
    var today = new Date()
    var dateStr =
      today.getMonth() + 1 + '/' + today.getDate() + '/' + today.getFullYear()
    var defaultName = t('import_name_prefix') + dateStr
    $('importer_name').val(defaultName)
    StepperState.settings.name = defaultName
  }

  // Initialize admin set state with pre-selected value
  function initAdminSetState() {
    var $adminSetSelect = $('#importer-admin-set')
    if ($adminSetSelect.length) {
      var currentVal = $adminSetSelect.val()
      if (currentVal && currentVal.trim() !== '') {
        StepperState.adminSetId = currentVal.trim()
        StepperState.adminSetName = $adminSetSelect.find('option:selected').text().trim()
      }
    }
  }

  function updateDownloadTemplateLink() {
    var $link = $('#download-csv-template-link')
    if (!$link.length) return
    var baseUrl = $link.data('sample-csv-url') || $link.attr('href')
    var adminSetId = $('#importer-admin-set').val()
    var href = baseUrl
    if (adminSetId && adminSetId.trim() !== '') {
      var sep = baseUrl.indexOf('?') >= 0 ? '&' : '?'
      href = baseUrl + sep + 'admin_set_id=' + encodeURIComponent(adminSetId.trim())
    }
    $link.attr('href', href)
  }

  // Navigate to step
  function goToStep(stepNum) {
    StepperState.currentStep = stepNum
    updateStepperUI()

    // Scroll to top, then move focus to the new step's heading
    $('html, body').animate({ scrollTop: 0 }, CONSTANTS.SCROLL_SPEED, function () {
      var $stepHeading = $('.step-content[data-step="' + stepNum + '"] .step-title h2')
      if ($stepHeading.length) {
        $stepHeading.first().focus()
      }
    })

    // Update review summary if going to step 3
    if (stepNum === 3) {
      updateReviewSummary()
    }
  }

  // Update stepper UI based on current step
  function updateStepperUI() {
    var step = StepperState.currentStep

    // Update step header
    $('.step-item').each(function () {
      var itemStep = parseInt($(this).data('step'))
      $(this).removeClass('active completed')

      if (itemStep === step) {
        $(this).addClass('active')
      } else if (itemStep < step) {
        $(this).addClass('completed')
      }
    })

    // Update step connectors
    $('.step-connector').each(function (index) {
      if (index < step - 1) {
        $(this).addClass('completed')
      } else {
        $(this).removeClass('completed')
      }
    })

    // Show/hide step content
    $('.step-content').hide()
    $('.step-content[data-step="' + step + '"]').show()

    // Update navigation buttons
    updateStepNavigation()
  }

  // Cached DOM selectors for updateStepNavigation
  var cachedSelectors = {
    nameInput: null,
    adminSetSelect: null,
    initialized: false
  }

  function initCachedSelectors() {
    if (!cachedSelectors.initialized) {
      cachedSelectors.nameInput = $('input[name$="[name]"][name*="importer"]').first()
      cachedSelectors.adminSetSelect = $('#importer-admin-set')
      cachedSelectors.initialized = true
    }
  }

  function isDefaultRightsStatementRequired() {
    if (StepperState.skipValidation || !StepperState.validationData) return false
    var missing = StepperState.validationData.missingRequired
    if (!missing || !Array.isArray(missing)) return false
    return missing.some(function (item) { return item && item.field === 'rights_statement' })
  }

  function didSkipValidation() {
    return StepperState.skipValidation === true
  }

  function updateStep2RightsStatementUI() {
    var required = isDefaultRightsStatementRequired()
    var skipped = didSkipValidation()
    var $alert = $('#default-rights-required-alert')
    var $hint = $('#default-rights-skipped-hint')
    var $label = $('.default-rights-statement-label')
    var $optionalSettings = $('#optional-settings')

    if ($alert.length) {
      $alert.toggle(required)
    }
    if ($hint.length) {
      $hint.toggle(skipped && !required)
    }
    if ($label.length) {
      var $asterisk = $label.find('.text-danger.default-rights-required-asterisk')
      if (required && !$asterisk.length) {
        $label.append(' <span class="text-danger default-rights-required-asterisk">*</span>')
      } else if (!required && $asterisk.length) {
        $asterisk.remove()
      }
    }
    if ((required || skipped) && $optionalSettings.length && !$optionalSettings.hasClass('show')) {
      $optionalSettings.addClass('show')
    }
  }

  // Update step navigation button states
  function updateStepNavigation() {
    var step = StepperState.currentStep

    if (step === 1) {
      var data = StepperState.validationData
      var isValid = data && data.isValid
      var hasWarnings = data && data.hasWarnings
      var canProceed = StepperState.skipValidation ||
        (StepperState.validated &&
          (isValid || StepperState.warningsAcked) &&
          (!hasWarnings || StepperState.warningsAcked))

      $('.step-content[data-step="1"] .step-next-btn').prop('disabled', !canProceed)
    } else if (step === 2) {
      initCachedSelectors()
      var name = (cachedSelectors.nameInput.length ? cachedSelectors.nameInput.val() : '').trim()
      var adminSetId = (cachedSelectors.adminSetSelect.length ? cachedSelectors.adminSetSelect.val() : '').trim()
      var rightsRequired = isDefaultRightsStatementRequired()
      var rightsValue = $('select[name="importer[parser_fields][rights_statement]"]').val()
      var hasRights = rightsValue && rightsValue.length > 0

      canProceed = name.length > 0 && adminSetId.length > 0 && (!rightsRequired || hasRights)
      StepperState.settings.name = name || StepperState.settings.name
      StepperState.adminSetId = adminSetId || StepperState.adminSetId
      $('.step-content[data-step="2"] .step-next-btn').prop('disabled', !canProceed)
      updateStep2RightsStatementUI()
    }
  }

  // Update review summary
  function updateReviewSummary() {
    var data = StepperState.validationData
    var settings = StepperState.settings

    // Files
    var filesHtml = StepperState.uploadedFiles
      .map(function (f) {
        var type = f.fileType === 'csv' ? 'CSV' : 'ZIP'
        var fromZip = f.fromZip ? ' — ' + t('detected_in_zip') : ''
        return (
          '<p><span class="text-muted small">' + type + ':</span> ' + escapeHtml(f.name) + ' (' + escapeHtml(f.size) + ')' + fromZip + '</p>'
        )
      })
      .join('')
    $('.review-files').html(filesHtml)

    // Records
    var totalItems = 0
    var recordsHtml
    if (data) {
      totalItems = data.collections.length + data.works.length + data.fileSets.length
      recordsHtml =
        '<p>' +
        t('review_total', {
          total: totalItems,
          collections: data.collections.length,
          works: data.works.length,
          file_sets: data.fileSets.length
        }) +
        '</p>'
    } else {
      recordsHtml = '<p class="text-muted">' + t('review_skipped') + '</p>'
    }
    $('.review-records').html(recordsHtml)

    // Settings - get admin set name from DOM first, then fallback to state
    var $currentAdminSet = $('#importer-admin-set')
    var adminSetName = t('not_selected')
    if ($currentAdminSet.length) {
      var selectedText = $currentAdminSet.find('option:selected').text().trim()
      var selectedValue = $currentAdminSet.val()
      if (selectedValue && selectedValue !== '' && selectedText !== t('admin_set_prompt')) {
        adminSetName = selectedText
      }
    }
    if (adminSetName === t('not_selected') && StepperState.adminSetName) {
      adminSetName = StepperState.adminSetName
    }
    var visibilityLabels = {
      open: t('visibility_public'),
      authenticated: t('visibility_institution'),
      restricted: t('visibility_private')
    }
    var visibilityName = visibilityLabels[settings.visibility]

    var settingsHtml =
      '<p><span class="text-muted small">' + t('review_name') + '</span> ' +
      escapeHtml(settings.name) +
      '</p>' +
      '<p><span class="text-muted small">' + t('review_admin_set') + '</span> ' +
      adminSetName +
      '</p>' +
      '<p><span class="text-muted small">' + t('review_visibility') + '</span> ' +
      visibilityName +
      '</p>'

    if (settings.rightsStatement) {
      settingsHtml += '<p><span class="text-muted small">' + t('review_rights') + '</span> ' + settings.rightsStatement + '</p>'
    }
    if (settings.limit) {
      settingsHtml += '<p><span class="text-muted small">' + t('review_limit') + '</span> ' + t('review_first_n_records', { count: settings.limit }) + '</p>'
    }

    $('.review-settings').html(settingsHtml)

    // Errors and warnings — derive from messages.issues so every severity is covered.
    // Row-level errors/warnings get a per-category breakdown beneath the summary line.
    var allIssues = (data && data.messages && data.messages.issues) || []
    var errorIssues = allIssues.filter(function (issue) { return issue.severity === 'error' })
    var warningIssues = allIssues.filter(function (issue) { return issue.severity === 'warning' })

    renderReviewIssueSection(errorIssues, '.review-errors', '.review-errors-list')
    renderReviewIssueSection(warningIssues, '.review-warnings', '.review-warnings-list')

    // Large import warning
    $('.total-items-count').text(totalItems)
    if (data && totalItems > CONSTANTS.IMPORT_SIZE_MODERATE) {
      $('.large-import-warning').show()
    } else {
      $('.large-import-warning').hide()
    }
  }

  // ============================================================================
  // FORM SUBMISSION & SUCCESS STATE
  // ============================================================================

  // Handle import submission
  function handleImportSubmit() {
    var $btn = $('#start-import-btn')
    var $form = $('#bulk-import-stepper-form')
    $btn
      .prop('disabled', true)
      .html('<span class="fa fa-spinner fa-spin"></span> ' + t('starting'))

    // Disable the file input so raw files aren't sent with the form
    $('#file-input').prop('disabled', true)

    // Only append uploaded file IDs in upload mode; in file_path mode the import_file_path
    // param is used and appending IDs would cause GuidedImportsController#create to ignore the path.
    if (StepperState.uploadMode === 'upload' && Array.isArray(StepperState.uploadedFiles)) {
      StepperState.uploadedFiles.forEach(function (f) {
        if (f.uploadId) {
          var $input = $('<input>', { type: 'hidden', name: 'uploaded_files[]' }).val(f.uploadId)
          $form.append($input)
        }
      })
    }

    // Submit the form so the request hits GuidedImportsController#create and creates the importer / enqueues job
    $form[0].submit()
  }

  // Look up mock validation data from cached demo scenarios JSON
  function getMockValidationData() {
    var scenario = StepperState.demoScenario || 'warning_combined'
    var data = StepperState.demoScenariosData
    if (!data || !data.scenarios || !data.scenarios[scenario]) return null
    return data.scenarios[scenario].response
  }

  // ============================================================================
  // NOTIFICATION FUNCTIONS
  // ============================================================================

  function showNotification(message, type) {
    type = type || 'info' // 'error', 'warning', 'info'

    var icons = {
      error: 'fa-times-circle',
      warning: 'fa-exclamation-triangle',
      info: 'fa-info-circle'
    }

    // Escape the message to prevent XSS
    var safeMessage = escapeHtml(message)

    var $notification = $(
      '<div class="upload-notification notification-' + type + '">' +
      '<span class="fa ' + icons[type] + ' upload-notification-icon"></span>' +
      '<div class="upload-notification-content">' + safeMessage + '</div>' +
      '<span class="fa fa-times upload-notification-close"></span>' +
      '</div>'
    )

    $('#upload-notifications').append($notification)

    // Click to dismiss
    $notification.find('.upload-notification-close').on('click', function () {
      $notification.fadeOut(CONSTANTS.NOTIFICATION_FADE_SPEED, function () {
        $(this).remove()
      })
    })
  }

  // Initialize on document ready and turbolinks load
  $(document).on('turbolinks:load', initBulkImportStepper)
})(jQuery, window.BulkraxUtils || {})