Events and Callbacks

/**
 * Fired immediately when the dropdown is about to be shown
 * @param e - Event object
 */
'show.bs.select': (e: Event) => void;

/**
 * Fired when the dropdown has been made visible (after CSS transitions)
 * @param e - Event object  
 */
'shown.bs.select': (e: Event) => void;

/**
 * Fired immediately when the dropdown is about to be hidden
 * @param e - Event object
 */
'hide.bs.select': (e: Event) => void;

/**
 * Fired when the dropdown has finished being hidden (after CSS transitions)
 * @param e - Event object
 */
'hidden.bs.select': (e: Event) => void;

// Handle dropdown visibility events
$('#mySelect').on('show.bs.select', function(e) {
  console.log('Dropdown about to show');
  // Optionally prevent showing: e.preventDefault();
});

$('#mySelect').on('shown.bs.select', function(e) {
  console.log('Dropdown is now visible');
  // Focus search input if live search is enabled
  $(this).next('.bootstrap-select').find('input').focus();
});

$('#mySelect').on('hide.bs.select', function(e) {
  console.log('Dropdown about to hide');
  // Save current state before hiding
  localStorage.setItem('lastSelection', $(this).val());
});

$('#mySelect').on('hidden.bs.select', function(e) {
  console.log('Dropdown is now hidden');
  // Clean up any temporary state
});

// Chain multiple event handlers
$('#mySelect')
  .on('show.bs.select', function() { $(this).addClass('dropdown-opening'); })
  .on('shown.bs.select', function() { $(this).removeClass('dropdown-opening').addClass('dropdown-open'); })
  .on('hidden.bs.select', function() { $(this).removeClass('dropdown-open'); });

/**
 * Fired when the selection changes
 * @param e - Event object with additional properties
 * @param clickedIndex - Index of the clicked option (if applicable)
 * @param isSelected - Whether the clicked option is now selected
 * @param previousValue - Previous selected value(s)
 */
'changed.bs.select': (e: Event, clickedIndex?: number, isSelected?: boolean, previousValue?: any) => void;

// Handle selection changes
$('#mySelect').on('changed.bs.select', function(e, clickedIndex, isSelected, previousValue) {
  const currentValue = $(this).selectpicker('val');
  const $option = $(this).find('option').eq(clickedIndex);
  
  console.log('Selection changed:', {
    current: currentValue,
    previous: previousValue,
    clickedIndex: clickedIndex,
    clickedOption: $option.val(),
    isSelected: isSelected
  });
  
  // Handle specific selection logic
  if (Array.isArray(currentValue) && currentValue.length > 3) {
    alert('Maximum 3 selections allowed');
    $(this).selectpicker('val', previousValue);
  }
});

// Track selection analytics
$('#trackingSelect').on('changed.bs.select', function(e, clickedIndex, isSelected) {
  const option = $(this).find('option').eq(clickedIndex);
  
  // Send analytics event
  analytics.track('option_selected', {
    select_id: $(this).attr('id'),
    option_value: option.val(),
    option_text: option.text(),
    is_selected: isSelected,
    total_selected: $(this).selectpicker('val').length
  });
});

// Dynamic styling based on selection
$('#dynamicSelect').on('changed.bs.select', function() {
  const count = $(this).selectpicker('val').length;
  
  if (count === 0) {
    $(this).selectpicker('setStyle', 'btn-secondary');
  } else if (count <= 2) {
    $(this).selectpicker('setStyle', 'btn-primary');
  } else {
    $(this).selectpicker('setStyle', 'btn-success');
  }
});

/**
 * Fired when the selectpicker has been fully loaded and initialized
 * @param e - Event object
 */
'loaded.bs.select': (e: Event) => void;

/**
 * Fired when the selectpicker display has been rendered
 * @param e - Event object
 */
'rendered.bs.select': (e: Event) => void;

/**
 * Fired when the selectpicker has been refreshed
 * @param e - Event object
 */
'refreshed.bs.select': (e: Event) => void;

/**
 * Fired when maximum options limit is reached
 * @param e - Event object
 */
'maxReached.bs.select': (e: Event) => void;

/**
 * Fired when maximum options limit is reached for a group
 * @param e - Event object
 */
'maxReachedGrp.bs.select': (e: Event) => void;

// Handle lifecycle events
$('#mySelect').on('loaded.bs.select', function(e) {
  console.log('Selectpicker fully loaded');
  // Perform post-initialization tasks
  $(this).closest('form').removeClass('loading');
});

$('#mySelect').on('rendered.bs.select', function(e) {
  console.log('Selectpicker rendered');
  // Update custom UI elements
  updateCustomBadges($(this));
});

$('#mySelect').on('refreshed.bs.select', function(e) {
  console.log('Selectpicker refreshed');
  // Reapply custom enhancements
  applyCustomStyling($(this));
});

// Initialize with lifecycle tracking
function initializeSelectpicker(selector) {
  $(selector)
    .on('loaded.bs.select', function() {
      $(this).data('loaded', true);
    })
    .on('refreshed.bs.select', function() {
      $(this).data('last-refresh', new Date());
    })
    .selectpicker();
}

// Handle max options events
$('#limitedSelect').on('maxReached.bs.select', function(e) {
  console.log('Maximum selection limit reached');
  alert('You cannot select more options');
});

$('#groupedSelect').on('maxReachedGrp.bs.select', function(e) {  
  console.log('Group selection limit reached');
  alert('Maximum selections reached for this group');
});

/**
 * Event delegation for dynamically added selectpickers
 */
$(document).on('changed.bs.select', '.dynamic-selectpicker', handler);

/**
 * Custom event creation and triggering
 */
function triggerCustomSelectEvent(selectElement: JQuery, eventName: string, data?: any): void {
  selectElement.trigger(eventName + '.bs.select', data);
}

// Event delegation for dynamic content
$(document).on('changed.bs.select', '.dynamic-selectpicker', function(e) {
  console.log('Dynamic selectpicker changed:', $(this).attr('id'));
});

// Add dynamic selectpickers
function addDynamicSelect() {
  const $newSelect = $('<select class="selectpicker dynamic-selectpicker">...</select>');
  $('#container').append($newSelect);
  $newSelect.selectpicker(); // Events automatically handled via delegation
}

// Custom event creation
function triggerCustomSelectEvent(selectElement, eventName, data) {
  selectElement.trigger(eventName + '.bs.select', data);
}

// Trigger custom events
$('#mySelect').on('validation.bs.select', function(e, isValid, errors) {
  if (!isValid) {
    $(this).selectpicker('setStyle', 'btn-danger');
    console.log('Validation errors:', errors);
  }
});

// Custom validation trigger
function validateSelection(selectElement) {
  const value = selectElement.selectpicker('val');
  const isValid = value && value.length > 0;
  const errors = isValid ? [] : ['Selection is required'];
  
  triggerCustomSelectEvent(selectElement, 'validation', [isValid, errors]);
}

// Multiple select coordination
$('.coordinated-select').on('changed.bs.select', function() {
  const $this = $(this);
  const group = $this.data('group');
  
  // Update related selects in the same group
  $('.coordinated-select[data-group="' + group + '"]').not($this).each(function() {
    // Custom coordination logic
    updateRelatedSelect($(this), $this.selectpicker('val'));
  });
});

/**
 * Prevent dropdown from opening
 */
$('#mySelect').on('show.bs.select', function(e) {
  if (shouldPreventOpening()) {
    e.preventDefault();
  }
});

/**
 * Conditionally prevent selection changes
 */
$('#restrictedSelect').on('changed.bs.select', function(e, clickedIndex, isSelected, previousValue) {
  if (!isValidSelection(clickedIndex, isSelected)) {
    // Revert to previous value
    $(this).selectpicker('val', previousValue);
    e.preventDefault();
  }
});

// Conditional dropdown opening
$('#conditionalSelect').on('show.bs.select', function(e) {
  if (!$(this).data('enabled') || $(this).hasClass('loading')) {
    e.preventDefault();
    console.log('Dropdown opening prevented');
  }
});

// Selection validation with reversion
$('#validatedSelect').on('changed.bs.select', function(e, clickedIndex, isSelected, previousValue) {
  const currentValue = $(this).selectpicker('val');
  
  // Example: Maximum 3 selections
  if (Array.isArray(currentValue) && currentValue.length > 3) {
    $(this).selectpicker('val', previousValue);
    alert('Maximum 3 selections allowed');
    return;
  }
  
  // Example: Required selection validation
  if ($(this).hasClass('required') && (!currentValue || currentValue.length === 0)) {
    $(this).selectpicker('val', previousValue);
    alert('At least one selection is required');
    return;
  }
});

// Confirmation for critical selections
$('#criticalSelect').on('changed.bs.select', function(e, clickedIndex, isSelected, previousValue) {
  const option = $(this).find('option').eq(clickedIndex);
  
  if (option.hasClass('critical') && isSelected) {
    if (!confirm(`Are you sure you want to select "${option.text()}"?`)) {
      $(this).selectpicker('val', previousValue);
    }
  }
});

// Debounced event handling
let changeTimeout;
$('#debouncedSelect').on('changed.bs.select', function() {
  const $this = $(this);
  clearTimeout(changeTimeout);
  
  changeTimeout = setTimeout(function() {
    // Handle change after debounce period
    processSelectionChange($this);
  }, 500);
});