DOM Selection and Traversal

/**
 * Select elements using CSS selectors or create jQuery objects from existing elements
 * @param selector - CSS selector string, DOM element, or jQuery object
 * @param context - Optional DOM element to limit selection scope
 * @returns jQuery object containing matched elements
 */
function $(selector: string | Element | jQuery, context?: Element | jQuery): jQuery;
function jQuery(selector: string | Element | jQuery, context?: Element | jQuery): jQuery;

// CSS selectors
$('div.container')
$('#header')
$('.nav-item')
$('input[type="text"]')
$('li:first-child')

// With context
$('.item', '#container')
$('span', document.getElementById('wrapper'))

// From elements
$(document.getElementById('myDiv'))
$(document.querySelectorAll('.items'))

/**
 * Find descendant elements matching the selector
 * @param selector - CSS selector string
 * @returns jQuery object containing matched descendants
 */
find(selector: string): jQuery;

/**
 * Filter elements to those matching the selector or function
 * @param selector - CSS selector string or filter function
 * @returns jQuery object with filtered elements
 */
filter(selector: string | function): jQuery;

// Filter by selector
$('div').filter('.highlighted')
$('li').filter('[data-active="true"]')

// Filter by function
$('.item').filter(function(index) {
  return $(this).data('priority') > 5;
})

/**
 * Remove elements matching the selector or function from selection
 * @param selector - CSS selector string or filter function
 * @returns jQuery object with remaining elements
 */
not(selector: string | function): jQuery;

/**
 * Test if any elements in selection match the selector
 * @param selector - CSS selector string
 * @returns true if any elements match, false otherwise
 */
is(selector: string): boolean;

/**
 * Find closest ancestor element matching selector (including self)
 * @param selector - CSS selector string
 * @param context - Optional element to stop searching at
 * @returns jQuery object containing closest matching ancestor
 */
closest(selector: string, context?: Element): jQuery;

/**
 * Get immediate parent of each element
 * @param selector - Optional selector to filter parents
 * @returns jQuery object containing parent elements
 */
parent(selector?: string): jQuery;

/**
 * Get all ancestor elements
 * @param selector - Optional selector to filter ancestors
 * @returns jQuery object containing all ancestors
 */
parents(selector?: string): jQuery;

/**
 * Get ancestors until reaching element matching selector
 * @param selector - Selector to stop at
 * @param filter - Optional selector to filter results
 * @returns jQuery object containing ancestors until match
 */
parentsUntil(selector: string, filter?: string): jQuery;

/**
 * Get direct child elements
 * @param selector - Optional selector to filter children
 * @returns jQuery object containing child elements
 */
children(selector?: string): jQuery;

/**
 * Get all child nodes including text and comment nodes
 * @returns jQuery object containing all child nodes
 */
contents(): jQuery;

/**
 * Get all sibling elements
 * @param selector - Optional selector to filter siblings
 * @returns jQuery object containing sibling elements
 */
siblings(selector?: string): jQuery;

/**
 * Get immediately following sibling
 * @param selector - Optional selector to filter result
 * @returns jQuery object containing next sibling
 */
next(selector?: string): jQuery;

/**
 * Get immediately preceding sibling
 * @param selector - Optional selector to filter result
 * @returns jQuery object containing previous sibling
 */
prev(selector?: string): jQuery;

/**
 * Get all following siblings
 * @param selector - Optional selector to filter results
 * @returns jQuery object containing all following siblings
 */
nextAll(selector?: string): jQuery;

/**
 * Get all preceding siblings
 * @param selector - Optional selector to filter results
 * @returns jQuery object containing all preceding siblings
 */
prevAll(selector?: string): jQuery;

/**
 * Get following siblings until reaching element matching selector
 * @param selector - Selector to stop at
 * @param filter - Optional selector to filter results
 * @returns jQuery object containing siblings until match
 */
nextUntil(selector: string, filter?: string): jQuery;

/**
 * Get preceding siblings until reaching element matching selector
 * @param selector - Selector to stop at
 * @param filter - Optional selector to filter results
 * @returns jQuery object containing siblings until match
 */
prevUntil(selector: string, filter?: string): jQuery;

/**
 * Filter elements that contain descendant matching target
 * @param target - Selector string or DOM element
 * @returns jQuery object containing elements with matching descendants
 */
has(target: string | Element): jQuery;

/**
 * Get zero-based index of element among its siblings
 * @param element - Optional element to get index of
 * @returns Index number or -1 if not found
 */
index(element?: Element | jQuery): number;

/**
 * Add elements to current selection
 * @param selector - Selector, elements, or jQuery object to add
 * @param context - Optional context for selector
 * @returns jQuery object with combined selection
 */
add(selector: string | Element | jQuery, context?: Element): jQuery;

/**
 * Add previous selection back to current selection
 * @param selector - Optional selector to filter previous selection
 * @returns jQuery object with current and previous selections
 */
addBack(selector?: string): jQuery;

/**
 * Get first element from selection
 * @returns jQuery object containing first element
 */
first(): jQuery;

/**
 * Get last element from selection
 * @returns jQuery object containing last element
 */
last(): jQuery;

/**
 * Get element at specific index from selection
 * @param index - Zero-based index (negative values count from end)
 * @returns jQuery object containing element at index
 */
eq(index: number): jQuery;

/**
 * Get elements at even indices (0, 2, 4, etc.)
 * @returns jQuery object containing elements at even indices
 */
even(): jQuery;

/**
 * Get elements at odd indices (1, 3, 5, etc.)
 * @returns jQuery object containing elements at odd indices
 */
odd(): jQuery;

/**
 * Return to previous selection in chaining
 * @returns Previous jQuery object in the chain
 */
end(): jQuery;

// Complex traversal chains
$('#container')
  .find('.widget')
  .filter('.active')
  .children('button')
  .not('.disabled');

// Finding and testing relationships
if ($('#myButton').closest('.modal').length) {
  // Button is inside a modal
}

// Building complex selections
$('.item')
  .has('img')
  .add('.featured')
  .addClass('highlighted');

// Core selection methods
$('li').first().addClass('first-item');
$('li').last().addClass('last-item');
$('li').eq(2).addClass('third-item');
$('li').even().addClass('even-item');
$('li').odd().addClass('odd-item');

// Chaining with end()
$('.item')
  .find('button')
  .addClass('button-style')
  .end()
  .addClass('item-style');

/**
 * Advanced element finding with context and results array
 * @param selector - CSS selector string
 * @param context - Optional context element
 * @param results - Optional array to push results into
 * @param seed - Optional pre-filtered element set
 * @returns Array of matched elements
 */
$.find(selector: string, context?: Element, results?: Element[], seed?: Element[]): Element[];

/**
 * Test if element is contained within context element
 * @param context - Container element
 * @param element - Element to test for containment
 * @returns true if element is contained within context
 */
$.contains(context: Element, element: Element): boolean;

/**
 * Escape special characters in CSS selectors
 * @param selector - Selector string to escape
 * @returns Escaped selector string safe for use in selectors
 */
$.escapeSelector(selector: string): string;

/**
 * Remove duplicate elements from array and sort by document order
 * @param array - Array of DOM elements
 * @returns Sorted array with duplicates removed
 */
$.uniqueSort(array: Element[]): Element[];

// Advanced finding
const elements = $.find('.item', document.getElementById('container'));

// Containment testing
if ($.contains(document.getElementById('wrapper'), targetElement)) {
  // targetElement is inside wrapper
}

// Escaping selectors with special characters
const safeSelector = $.escapeSelector('my.special:id');
$('#' + safeSelector);