Add support for returning the first element matching a selector

And a minor refactoring of matchElementAgainstSelectors().

Author: cdoublev

lib/match/selector.js

@@ -1449,11 +1449,12 @@ function matchComplexSelector(element, selector, options) {
  * @param {Element} element
  * @param {*[]} selector
  * @param {object} [options]
+ * @param {boolean} [all]
  * @returns {object[]|null}
  * @see {@link https://drafts.csswg.org/selectors-4/#match-a-selector-against-an-element}
  */
-function matchElementAgainstSelectors(element, selector, options) {
-    if (options.all) {
+function matchElementAgainstSelectors(element, selector, options, all) {
+    if (all) {
         return selector.filter(selector => matchComplexSelector(element, selector, options))
     }
     return selector.some(selector => matchComplexSelector(element, selector, options))
@@ -1472,10 +1473,11 @@ function matchPseudoElementAgainstSelectors(pseudo, selector, options) { }
  * @param {Element[]} trees
  * @param {*[]} selector
  * @param {object} [options]
- * @returns {Element[]}
+ * @param {boolean} [first]
+ * @returns {Element|Element[]}
  * @see {@link https://drafts.csswg.org/selectors-4/#match-a-selector-against-a-tree}
  */
-function matchTreesAgainstSelectors(trees, selector, options = {}) {
+function matchTreesAgainstSelectors(trees, selector, options = {}, first) {
 
     // Assert: all trees share the same root
 
@@ -1491,6 +1493,9 @@ function matchTreesAgainstSelectors(trees, selector, options = {}) {
         options = roots ? { ...options, scope: tree, tree } : { ...options, tree }
         for (const element of traverse(tree, options)) {
             if (matchElementAgainstSelectors(element, selector, options)) {
+                if (first) {
+                    return selected
+                }
                 selected.push(element)
             }
             pseudos?.forEach(type => {

lib/resolve.js

@@ -399,7 +399,7 @@ function getSelectorSpecificity(selector) {
  */
 function getDeclarationSpecificity({ context }, element) {
     const [...selectors] = context.selectors
-    const matches = matchElementAgainstSelectors(element, selectors.pop(), { ...context, all: true })
+    const matches = matchElementAgainstSelectors(element, selectors.pop(), context, true)
     return mergeSpecificities(
         // Highest specificity among complex selectors matching `element` in the innermost most style rule
         getHighestSpecificity(matches.map(getSelectorSpecificity)),