Types and Interfaces

/**
 * Interface representing an option item in the select component
 * Can be extended with custom properties as needed
 */
interface NgOption {
  /** Allow any additional custom properties */
  [name: string]: any;
  /** Internal index of the option */
  index?: number;
  /** Unique HTML ID for accessibility */
  htmlId?: string;
  /** Whether this option is currently selected */
  selected?: boolean;
  /** Whether this option is disabled and cannot be selected */
  disabled?: boolean;
  /** Whether this option is currently marked/highlighted */
  marked?: boolean;
  /** Display label for the option */
  label?: string;
  /** Value of the option (can be any type) */
  value?: any;
  /** Parent option for grouped options */
  parent?: NgOption;
  /** Child options for group headers */
  children?: NgOption[];
}

/**
 * Union type for dropdown positioning options
 * Determines where the dropdown panel appears relative to the select input
 */
type DropdownPosition = 'top' | 'right' | 'bottom' | 'left' | 'auto';

/**
 * Enhanced dropdown position type with additional positioning control
 */
interface DropdownPositionOptions {
  /** Primary position preference */
  position: DropdownPosition;
  /** Whether to flip position if there's insufficient space */
  autoFlip?: boolean;
  /** Custom offset from the select input */
  offset?: {x: number, y: number};
}

/**
 * Function type for adding custom tags/items to the selection
 * Used when addTag property is set to a function
 */
type AddTagFn = (term: string) => any | Promise<any>;

/**
 * Function type for comparing items to determine equality
 * Used for tracking selections and preventing duplicates
 */
type CompareWithFn = (a: any, b: any) => boolean;

/**
 * Function type for custom search/filter logic
 * Return true if item matches the search term
 */
type SearchFn = (term: string, item: any) => boolean;

/**
 * Function type for generating group values from grouped items
 * Used when groupBy is set and custom group processing is needed
 */
type GroupValueFn = (key: string | any, children: any[]) => string | any;

/**
 * Function type for custom keyboard event handling
 * Return true to prevent default behavior
 */
type KeyDownFn = (event: KeyboardEvent) => boolean;

/**
 * Function type for trackBy optimization in large lists
 * Should return unique identifier for each item
 */
type TrackByFn = (index: number, item: any) => any;

/**
 * Function type for custom item loading/fetching
 * Used with typeahead functionality for remote data
 */
type LoadItemsFn = (term: string) => Observable<any[]> | Promise<any[]> | any[];

/**
 * Function type for custom clear confirmation
 * Return true to proceed with clear, false to cancel
 */
type ClearConfirmFn = (items: any[]) => boolean | Promise<boolean>;

/**
 * Event payload for search events
 * Contains current search term and filtered items
 */
interface SearchEvent {
  /** Current search/filter term */
  term: string;
  /** Items matching the current search term */
  items: any[];
}

/**
 * Event payload for scroll events during virtual scrolling
 * Contains information about currently visible range
 */
interface ScrollEvent {
  /** Starting index of visible items */
  start: number;
  /** Ending index of visible items */
  end: number;
}

/**
 * Event payload for change events
 * Contains previous and current values
 */
interface ChangeEvent {
  /** Previously selected value(s) */
  previousValue: any;
  /** Currently selected value(s) */
  currentValue: any;
  /** Whether the change was triggered by user action */
  isUserInput: boolean;
}

/**
 * Event payload for add/remove events
 * Contains information about the item being added or removed
 */
interface ItemEvent {
  /** The item being added or removed */
  item: any;
  /** Index of the item in the items array */
  index: number;
  /** Whether this was triggered by user action */
  isUserInput: boolean;
}

/**
 * Event payload for focus/blur events
 * Contains event details and current component state
 */
interface FocusEvent {
  /** The original DOM event */
  event: Event;
  /** Current selected value(s) */
  value: any;
  /** Whether component has valid selection */
  hasValue: boolean;
}

/**
 * Enum defining keyboard key codes used for navigation
 * Follows modern KeyboardEvent.key standard
 */
enum KeyCode {
  Tab = 'Tab',
  Enter = 'Enter',
  Esc = 'Escape',
  Space = ' ',
  ArrowUp = 'ArrowUp',
  ArrowDown = 'ArrowDown',
  Backspace = 'Backspace'
}

/**
 * Interface for keyboard navigation configuration
 */
interface KeyboardConfig {
  /** Keys that open the dropdown */
  openKeys: KeyCode[];
  /** Keys that close the dropdown */
  closeKeys: KeyCode[];
  /** Keys that navigate up in the list */
  upKeys: KeyCode[];
  /** Keys that navigate down in the list */
  downKeys: KeyCode[];
  /** Keys that select the current item */
  selectKeys: KeyCode[];
  /** Keys that clear the selection */
  clearKeys: KeyCode[];
  /** Whether to prevent default browser behavior */
  preventDefault: boolean;
}

/**
 * Interface for panel dimension calculations used in virtual scrolling
 */
interface PanelDimensions {
  /** Height of individual items in pixels */
  itemHeight: number;
  /** Total height of the scrollable panel */
  panelHeight: number;
  /** Number of items that fit in the visible viewport */
  itemsPerViewport: number;
  /** Additional buffer items to render outside viewport */
  bufferSize: number;
}

/**
 * Interface for virtual scroll calculation results
 * Used by NgDropdownPanelService for performance optimization
 */
interface ItemsRangeResult {
  /** Total height needed for scrollbar calculation */
  scrollHeight: number;
  /** Top padding to maintain correct scroll position */
  topPadding: number;
  /** Bottom padding for proper scrollbar sizing */
  bottomPadding: number;
  /** Start index of items to render */
  start: number;
  /** End index of items to render */
  end: number;
  /** Total number of items being virtualized */
  totalItems: number;
}

/**
 * Configuration interface for virtual scrolling behavior
 */
interface VirtualScrollConfig {
  /** Enable virtual scrolling */
  enabled: boolean;
  /** Number of items to render outside visible area */
  bufferAmount: number;
  /** Minimum number of items before virtual scroll activates */
  threshold: number;
  /** Fixed height for all items (improves performance) */
  itemHeight?: number;
  /** Dynamic height calculation function */
  itemHeightFn?: (item: any, index: number) => number;
}

/**
 * Interface defining the contract for selection model implementations
 * Allows for custom selection behavior and state management
 */
interface SelectionModel {
  /** Array of currently selected options */
  value: NgOption[];
  
  /**
   * Select an item and update the model
   */
  select(item: NgOption, multiple: boolean, selectableGroupAsModel: boolean): void;
  
  /**
   * Unselect an item and update the model
   */
  unselect(item: NgOption, multiple: boolean): void;
  
  /**
   * Clear all selections with optional disabled item preservation
   */
  clear(keepDisabled: boolean): void;
  
  /**
   * Check if an item is currently selected
   */
  isSelected(item: NgOption): boolean;
  
  /**
   * Get all selected values (not NgOption objects)
   */
  getSelectedValues(): any[];
}

/**
 * Factory function type for creating selection model instances
 */
type SelectionModelFactory = () => SelectionModel;

/**
 * Configuration interface for selection behavior
 */
interface SelectionConfig {
  /** Maximum number of items that can be selected */
  maxItems?: number;
  /** Minimum number of items that must be selected */
  minItems?: number;
  /** Custom validation function for selections */
  validator?: (selectedItems: any[]) => boolean;
  /** Whether to automatically clear invalid selections */
  autoClearInvalid: boolean;
}

/**
 * Union type for built-in appearance options
 */
type AppearanceType = 'default' | 'material' | 'bootstrap' | 'outline' | 'minimal';

/**
 * Interface for theme customization
 */
interface ThemeConfig {
  /** Name of the theme */
  name: string;
  /** CSS class names for different component states */
  classes: {
    container: string;
    single: string;
    multiple: string;
    dropdown: string;
    option: string;
    optionSelected: string;
    optionDisabled: string;
    optionMarked: string;
    label: string;
    clear: string;
    arrow: string;
    loading: string;
  };
  /** Custom CSS properties for theme variables */
  properties?: {[key: string]: string};
}

/**
 * Configuration for custom styling
 */
interface StyleConfig {
  /** Custom CSS classes to apply */
  classes?: {[key: string]: string};
  /** Inline styles to apply */
  styles?: {[key: string]: string};
  /** Theme configuration */
  theme?: ThemeConfig;
}

/**
 * Interface for validation result information
 */
interface ValidationResult {
  /** Whether the current value is valid */
  isValid: boolean;
  /** Array of validation error messages */
  errors: string[];
  /** Validation metadata */
  metadata?: {[key: string]: any};
}

/**
 * Function type for custom validation logic
 */
type ValidatorFn = (value: any) => ValidationResult | null;

/**
 * Interface for validation configuration
 */
interface ValidationConfig {
  /** Array of validator functions to apply */
  validators: ValidatorFn[];
  /** Whether to validate on value change */
  validateOnChange: boolean;
  /** Whether to validate on blur */
  validateOnBlur: boolean;
  /** Custom error message formatter */
  errorFormatter?: (errors: string[]) => string;
}

/**
 * Interface for reactive forms integration
 */
interface ReactiveFormsIntegration {
  /** Form control instance */
  control: AbstractControl;
  /** Validation state */
  validationState: ValidationResult;
  /** Touch state */
  touched: boolean;
  /** Dirty state */
  dirty: boolean;
}

/**
 * Interface for Observable/RxJS integration
 */
interface ObservableIntegration {
  /** Observable for item loading */
  items$: Observable<any[]>;
  /** Observable for search term changes */
  searchTerm$: Observable<string>;
  /** Observable for selection changes */
  selection$: Observable<any>;
  /** Loading state observable */
  loading$: Observable<boolean>;
}

/**
 * Type for async data loading patterns
 */
type AsyncDataSource = Observable<any[]> | Promise<any[]> | (() => Observable<any[]>) | (() => Promise<any[]>);