ulQuerySelector

ulQuerySelector is a JavaScript utility function that extends the native DOM query capabilities. It provides a single API to locate elements and can search across the document's light DOM and, optionally, its shadow DOM.

Usage: ulQuerySelector(root, selector, options). The root can be a Document, Element, or ShadowRoot; the selector is a CSS string. Options may include all (return all matches) and includeShadow (search inside shadow roots).

Return value: By default, it returns the first matching Element or null. If options.all is true, it returns an array of Elements. When includeShadow is enabled, the function traverses shadow roots under the root to collect matches.

Rationale and scope: ulQuerySelector is not part of the official DOM API. It is typically provided by UI libraries or test frameworks as a convenience wrapper around existing selectors, often with extended reach into shadow DOM.

Examples: ulQuerySelector(document, '#main'); ulQuerySelector(document, '.button', { all: true, includeShadow: true });

Limitations: Performance depends on implementation; cross-browser support varies. It is not standardized, so compatibility and behavior may differ between libraries. When adopting it, refer to the specific library documentation and consider any necessary polyfills for broader environments.