p_css 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 223962d85169a337ff087e759a5bce186ece7182cd15ead418c280228fdde208
-  data.tar.gz: 4ccd0ca9e312dec47fc8f41f4d0b02d6918f86c47279d463f1c6c3e2e75549b8
+  metadata.gz: caf08474039a751417ef1a6469b5e115206a0d7347234f13b703cf23c02e687f
+  data.tar.gz: 6f2f93498e29789e8d2c95f97b307835c5e4706d87af5b88056213272c650f96
 SHA512:
-  metadata.gz: 9a4e563505c86e0939c03410c1d75be48b5fc1e9b9ada13dc422ee0b290dba215a94d4cd5dced0c2c4984cd15770bd2797b667436b77709766e7c9d64b750280
-  data.tar.gz: dae2b3b18a78f04eb9dc9babd31e0b1f7e17102740f2fd4cfe34112b24095c8d2c1453e2e67ffb0cd91949d31c35ea4ef42d71c620d8cc0c86cfb67632592f18
+  metadata.gz: fff681ce658d521a7335492339f3e5a6510eabe7f69698af6ed33ff4f85d0e52901d21f2717efc574605a663cfdd2a29a5bbc74a7ef261fa1766c53b3fe1e4fc
+  data.tar.gz: 284c266752d7655da99c9a305c8555c5003f0316befc72b59b3da1e0e480c40e17b0e00440e28c9527ddee665a8a6ad8be9a74596d9e83319932e6724bb96ed3

data/README.md

@@ -40,6 +40,7 @@ is hardwired in.
 | AnB microsyntax | `CSS.parse_anb` | Syntax 4 §6.7 |
 | Specificity | `CSS.specificity` | Selectors §16 |
 | Selector matcher | `CSS.matches?` | Selectors 4 |
+| Tree queries | `CSS.select_all`, `CSS.select_first`, `CSS.closest` | Selectors 4 |
 | Nesting de-sugar | `CSS.desugar` | Nesting 1 |
 | Media query parser | `CSS.parse_media_query_list` | Media Queries 4 |
 | Media query evaluator | `CSS.media_matches?` | Media Queries 4 |
@@ -134,7 +135,7 @@ attr.matcher                        # => :exact
 attr.case_flag                      # => :i
 
 nth = compound.components[1]
-nth.argument                        # => CSS::Selectors::AnB(step: 2, offset: 1)
+nth.argument                        # => CSS::Selectors::AnB(step: 2, offset: 1, of: nil)
 ```
 
 The selector parser also accepts the prelude of a parsed rule directly (the
@@ -179,13 +180,38 @@ active = doc.at_css('li.active')
 CSS.matches?(active, 'li:nth-child(2n)')                 # => true
 CSS.matches?(active, ':is(.active, .selected)')          # => true
 CSS.matches?(active, 'ul > li:not(:first-child)')        # => true
+CSS.matches?(active, 'li:nth-child(1 of .active)')       # => true
+CSS.matches?(doc.at_css('ul'), 'ul:has(> .active)')      # => true
 ```
 
-Stateful pseudo-classes (`:hover`, `:focus`, `:visited`, validity API states,
-etc.) return `false` by default — there's no UA in the loop. Pass a `state:`
-Hash to opt in; see [Stateful pseudo-classes](#stateful-pseudo-classes)
-below. `:has()` is not yet implemented (its argument is kept as opaque
-component values).
+Supported Selectors-4 features include `:has()` (relative selector list),
+`:nth-child(An+B of S)`, and namespace prefixes (`*|name`, `|name`; a declared
+prefix is rejected — there is no `@namespace` mechanism). `:empty` follows
+Selectors-4 (whitespace-only content is `:empty`); pass
+`empty_allows_whitespace: false` for the real-browser / Selectors-3 behaviour.
+
+Stateful pseudo-classes (`:hover`, `:focus`, `:visited`, and the
+constraint-validation states `:valid` / `:invalid` / `:user-valid` /
+`:user-invalid` / `:indeterminate`) return `false` by default — there's no UA
+in the loop. Pass a `state:` Hash to opt in; see
+[Stateful pseudo-classes](#stateful-pseudo-classes) below.
+
+#### Tree queries and `:scope`
+
+`select_all` / `select_first` walk a root's descendants (document order);
+`closest` walks inclusive ancestors. `:scope` matches the elements passed via
+`scope:` (defaulting to `:root`):
+
+```ruby
+row = doc.at_css('ul')
+
+CSS.select_all(row, '.active')                       # => [<li class="active">]
+CSS.select_first(row, 'li')                          # => <li>one</li>
+CSS.closest(active, 'ul')                            # => <ul>
+
+# `:scope` resolves against the supplied scoping element.
+CSS.select_all(row, ':scope > li', scope: row)       # => the three <li>s
+```
 
 ### Nesting de-sugar
 
@@ -271,8 +297,9 @@ encapsulation are not modeled — `@layer` / `@supports` / `@scope` /
 ### Stateful pseudo-classes
 
 `:hover`, `:focus`, `:focus-within`, `:focus-visible`, `:active`, `:visited`,
-and `:target` return `false` from the matcher by default. Pass a `state:`
-Hash to override:
+`:target`, and the constraint-validation states (`:valid`, `:invalid`,
+`:user-valid`, `:user-invalid`, `:indeterminate`) return `false` from the
+matcher by default. Pass a `state:` Hash to override:
 
 ```ruby
 state = {
@@ -336,9 +363,9 @@ r.to_s       # => "U+1000-10FF"
 
 These are deliberate omissions; pull requests welcome:
 
-- Selectors Level 4 namespace prefixes (`ns|*`)
+- Declared namespace prefixes / `@namespace` (only `*|name` and `|name` are
+  supported; a declared prefix like `svg|rect` is rejected)
 - The column combinator `||`
-- `:has()` (relative selector list — needs a small AST extension)
 - Strict/forgiving selector list distinction
 - `@scope` proximity and the rest of the Cascade Layers spec
 - Layout calculations (`display: block` vs flex sizing, `overflow: hidden`

data/lib/css/nesting.rb

@@ -33,7 +33,16 @@ module CSS
     # effective selector; subsequent rules are the nested ones recursively
     # desugared.
     def desugar_qualified_rule(rule, parent_list:)
-      own       = Selectors::Parser.parse_selector_list(rule.prelude)
+      # Nested rules follow the <relative-selector-list> grammar (a selector
+      # may begin with a combinator); top-level rules keep the strict parser,
+      # so a top-level leading combinator is still a syntax error.
+      own =
+        if parent_list
+          Selectors::Parser.parse_nesting_selector_list(rule.prelude)
+        else
+          Selectors::Parser.parse_selector_list(rule.prelude)
+        end
+
       effective = parent_list ? substitute_nesting(own, parent_list) : own
 
       decls, rules = partition_block_items(rule.block.items, parent_list: effective)

data/lib/css/selectors/matcher.rb

@@ -17,8 +17,9 @@ module CSS
     #
     # Pseudo-classes that depend on user-agent state (`:hover`, `:focus`,
     # `:visited`, etc.) return false by default; pass an explicit `state:`
-    # mapping to opt into stateful matching. Validity-API and viewport-
-    # only states (`:fullscreen`, `:valid`, …) are not exposed.
+    # mapping to opt into stateful matching. Constraint-validation states
+    # (`:valid`, `:invalid`, `:user-valid`, `:user-invalid`, `:indeterminate`)
+    # can't be derived from the DOM, so they are also `state:` opt-ins.
     module Matcher
       extend self
 
@@ -30,7 +31,10 @@ module CSS
       # User-agent state pseudos. The matcher returns `false` for these
       # unless the caller passes a `state:` Hash describing which
       # elements (or "all") should match.
-      STATEFUL_PSEUDOS = %w[hover focus focus-within focus-visible active visited target].to_set.freeze
+      STATEFUL_PSEUDOS = %w[
+        hover focus focus-within focus-visible active visited target
+        valid invalid user-valid user-invalid indeterminate
+      ].to_set.freeze
 
       # Per spec these states propagate up the ancestor chain — if a
       # descendant is hovered/active/contains-focus, the ancestors
@@ -45,8 +49,24 @@ module CSS
 
       EMPTY_CLASSES = [].freeze
 
-      def matches?(element, selector, cache: nil, state: nil)
-        sel = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
+      # Private key under which the `:scope` set is carried on the `state`
+      # object, so it threads through the deep match recursion without changing
+      # every method signature. A user `state` Hash is keyed by pseudo names,
+      # so this unique object never collides.
+      SCOPE_KEY = Object.new.freeze
+
+      # Private key carrying the `:empty` whitespace policy on `state`. Only
+      # stamped when the caller opts out of the default (whitespace allowed),
+      # so the key's absence means "Selectors-4 default".
+      EMPTY_WS_KEY = Object.new.freeze
+
+      # `scope` (an element, Array, or Set) is the set `:scope` matches; with
+      # none, `:scope` falls back to `:root`. `empty_allows_whitespace`
+      # (default true, Selectors-4) controls `:empty`: when false, any
+      # non-empty text — including whitespace — disqualifies (real browsers).
+      def matches?(element, selector, cache: nil, state: nil, scope: nil, empty_allows_whitespace: true)
+        sel   = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
+        state = build_state(state, scope, empty_allows_whitespace)
 
         case sel
         when SelectorList
@@ -60,8 +80,100 @@ module CSS
         end
       end
 
+      # querySelectorAll-style: every descendant of `roots` (an element or
+      # array of elements), in document order, matching `selector`. `:scope`
+      # honours the `scope:` option (default `:root`).
+      def select_all(roots, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+        sel   = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
+        state = build_state(state, scope, empty_allows_whitespace)
+        cache = {}
+        list  = roots.is_a?(Array) ? roots : [roots]
+        out   = []
+
+        list.each { collect_matches(_1, sel, cache, state, out) }
+
+        list.size > 1 ? dedup_nodes(out) : out
+      end
+
+      def select_first(roots, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+        sel   = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
+        state = build_state(state, scope, empty_allows_whitespace)
+        cache = {}
+        list  = roots.is_a?(Array) ? roots : [roots]
+
+        list.each do |root|
+          hit = first_match(root, sel, cache, state)
+          return hit if hit
+        end
+
+        nil
+      end
+
+      # Nearest inclusive-ancestor of `element` matching `selector`
+      # (Element#closest).
+      def closest(element, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+        sel   = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
+        state = build_state(state, scope, empty_allows_whitespace)
+        cache = {}
+        cur   = element
+
+        while cur
+          return cur if matches?(cur, sel, cache: cache, state: state)
+
+          cur = parent_element(cur)
+        end
+
+        nil
+      end
+
       private
 
+      # Folds the `scope:` set and the `:empty` whitespace policy onto the
+      # user `state` Hash, so both thread through the match recursion. A no-op
+      # at the defaults (no scope, whitespace allowed), so recursive matches?
+      # calls — which always pass the defaults — leave a carried flag intact.
+      def build_state(state, scope, empty_allows_whitespace)
+        state = with_scope(state, scope) unless scope.nil?
+        state = (state || {}).merge(EMPTY_WS_KEY => false) unless empty_allows_whitespace
+        state
+      end
+
+      def with_scope(state, scope)
+        set =
+          case scope
+          when Set   then scope.to_a
+          when Array then scope
+          else            [scope]
+          end
+
+        (state || {}).merge(SCOPE_KEY => set)
+      end
+
+      def collect_matches(node, sel, cache, state, out)
+        element_children(node).each do |child|
+          out << child if matches?(child, sel, cache: cache, state: state)
+
+          collect_matches(child, sel, cache, state, out)
+        end
+      end
+
+      def first_match(node, sel, cache, state)
+        element_children(node).each do |child|
+          return child if matches?(child, sel, cache: cache, state: state)
+
+          found = first_match(child, sel, cache, state)
+          return found if found
+        end
+
+        nil
+      end
+
+      def dedup_nodes(nodes)
+        result = []
+        nodes.each {|n| result << n unless result.any? { same_node?(_1, n) } }
+        result
+      end
+
       # Walks the complex selector right-to-left starting at the rightmost
       # compound. Each combinator either succeeds against ancestors /
       # siblings of the current candidate or fails the whole match.
@@ -114,8 +226,8 @@ module CSS
 
       def match_simple(element, simple, cache, state)
         case simple
-        when TypeSelector      then tag_of(element, cache).casecmp?(simple.name)
-        when UniversalSelector then true
+        when TypeSelector      then match_type(element, simple, cache)
+        when UniversalSelector then simple.namespace == '' ? in_no_namespace?(element) : true
         when IdSelector        then id_of(element, cache) == simple.name
         when ClassSelector     then classes_of(element, cache).include?(simple.name)
         when AttributeSelector then match_attribute(element, simple)
@@ -169,6 +281,25 @@ module CSS
         v.to_s.split(' ')
       end
 
+      # Type matching ---------------------------------------------------
+
+      # A bare `name` / `*|name` matches by local name in any namespace; a
+      # `|name` (namespace `''`) additionally requires the element to be in no
+      # namespace. The no-namespace constraint is enforced only when the
+      # element exposes namespace info (`respond_to?(:namespace)`); otherwise
+      # it is skipped and matching is by local name alone.
+      def match_type(element, sel, cache)
+        return false unless tag_of(element, cache).casecmp?(sel.name)
+
+        sel.namespace == '' ? in_no_namespace?(element) : true
+      end
+
+      def in_no_namespace?(element)
+        return true unless element.respond_to?(:namespace)
+
+        element.namespace.nil?
+      end
+
       # Attribute matching ----------------------------------------------
 
       def match_attribute(element, attr_sel)
@@ -205,20 +336,20 @@ module CSS
         case name
         when 'is', 'where', 'matches'   then match_selector_list_arg(element, pc.argument, cache, state)
         when 'not'                       then negate_selector_list_arg(element, pc.argument, cache, state)
-        when 'has'                       then false
+        when 'has'                       then match_has(element, pc.argument, cache, state)
         when 'root'                      then parent_element(element).nil?
-        when 'scope'                     then parent_element(element).nil?
+        when 'scope'                     then match_scope(element, state)
         when 'first-child'               then previous_element(element).nil?
         when 'last-child'                then next_element(element).nil?
         when 'only-child'                then previous_element(element).nil? && next_element(element).nil?
         when 'first-of-type'             then same_type_previous(element).nil?
         when 'last-of-type'              then same_type_next(element).nil?
         when 'only-of-type'              then same_type_previous(element).nil? && same_type_next(element).nil?
-        when 'nth-child'                 then match_nth(element, pc.argument, of_type: false, from_end: false)
-        when 'nth-last-child'            then match_nth(element, pc.argument, of_type: false, from_end: true)
-        when 'nth-of-type'               then match_nth(element, pc.argument, of_type: true,  from_end: false)
-        when 'nth-last-of-type'          then match_nth(element, pc.argument, of_type: true,  from_end: true)
-        when 'empty'                     then empty?(element)
+        when 'nth-child'                 then match_nth(element, pc.argument, of_type: false, from_end: false, cache:, state:)
+        when 'nth-last-child'            then match_nth(element, pc.argument, of_type: false, from_end: true,  cache:, state:)
+        when 'nth-of-type'               then match_nth(element, pc.argument, of_type: true,  from_end: false, cache:, state:)
+        when 'nth-last-of-type'          then match_nth(element, pc.argument, of_type: true,  from_end: true,  cache:, state:)
+        when 'empty'                     then empty?(element, empty_allows_whitespace?(state))
         when 'link', 'any-link'          then link?(element)
         when 'enabled'                   then disableable?(element) && !disabled?(element)
         when 'disabled'                  then disabled?(element)
@@ -228,6 +359,7 @@ module CSS
         when 'read-only'                 then read_only?(element)
         when 'read-write'                then read_write?(element)
         when 'placeholder-shown'         then placeholder_shown?(element)
+        when 'default'                   then default?(element)
         when 'lang'                      then match_lang(element, pc.argument)
         when 'dir'                       then match_dir(element, pc.argument)
         when 'defined'                   then true
@@ -271,10 +403,106 @@ module CSS
         arg.is_a?(SelectorList) && !matches?(element, arg, cache: cache, state: state)
       end
 
-      def match_nth(element, anb, of_type:, from_end:)
+      # `:scope` matches the scoping roots supplied via `scope:` (carried on
+      # `state` under SCOPE_KEY); with none it falls back to `:root`.
+      def match_scope(element, state)
+        set = state && state[SCOPE_KEY]
+
+        set ? set.any? { same_node?(_1, element) } : parent_element(element).nil?
+      end
+
+      # `:has(...)` — searches the anchor's subtree (descendant / child) or its
+      # following siblings (`+` / `~`) for a subject whose right-to-left match
+      # chains back to the anchor via the relative selector's leading
+      # combinator. Each relative selector is tried independently.
+      def match_has(anchor, argument, cache, state)
+        return false unless argument.is_a?(RelativeSelectorList)
+
+        argument.selectors.any? { has_relative?(anchor, _1, cache, state) }
+      end
+
+      def has_relative?(anchor, rel, cache, state)
+        return has_in_subtree?(anchor, rel, anchor, cache, state) unless sibling_leading?(rel.combinator)
+
+        sib = next_element(anchor)
+
+        while sib
+          return true if rel_at?(sib, rel, rel.complex.compounds.size - 1, anchor, cache, state)
+          return true if has_in_subtree?(sib, rel, anchor, cache, state)
+
+          sib = next_element(sib)
+        end
+
+        false
+      end
+
+      def has_in_subtree?(node, rel, anchor, cache, state)
+        element_children(node).each do |child|
+          return true if rel_at?(child, rel, rel.complex.compounds.size - 1, anchor, cache, state)
+          return true if has_in_subtree?(child, rel, anchor, cache, state)
+        end
+
+        false
+      end
+
+      # Matches the relative selector's compound at `index` against `element`,
+      # then walks the remaining compounds right-to-left; at index 0 the chain
+      # must connect back to the anchor via the leading combinator.
+      def rel_at?(element, rel, index, anchor, cache, state)
+        return false if element.nil?
+        return false unless match_compound(element, rel.complex.compounds[index], cache, state)
+        return connects_to_anchor?(element, rel.combinator, anchor) if index.zero?
+
+        case rel.complex.combinators[index - 1]
+        when :child
+          rel_at?(parent_element(element), rel, index - 1, anchor, cache, state)
+        when :descendant
+          a = parent_element(element)
+          a = parent_element(a) until a.nil? || rel_at?(a, rel, index - 1, anchor, cache, state)
+          !a.nil?
+        when :next_sibling
+          rel_at?(previous_element(element), rel, index - 1, anchor, cache, state)
+        when :subsequent_sibling
+          s = previous_element(element)
+          s = previous_element(s) until s.nil? || rel_at?(s, rel, index - 1, anchor, cache, state)
+          !s.nil?
+        end
+      end
+
+      def connects_to_anchor?(element, leading, anchor)
+        case leading
+        when :child
+          same_node?(parent_element(element), anchor)
+        when :descendant
+          a = parent_element(element)
+          a = parent_element(a) until a.nil? || same_node?(a, anchor)
+          !a.nil?
+        when :next_sibling
+          same_node?(previous_element(element), anchor)
+        when :subsequent_sibling
+          s = previous_element(element)
+          s = previous_element(s) until s.nil? || same_node?(s, anchor)
+          !s.nil?
+        end
+      end
+
+      def sibling_leading?(combinator)
+        combinator == :next_sibling || combinator == :subsequent_sibling
+      end
+
+      def match_nth(element, anb, of_type:, from_end:, cache:, state:)
         return false unless anb.is_a?(AnB)
 
-        index = nth_index(element, of_type:, from_end:)
+        index =
+          if anb.of
+            # `of S` — the element must itself match S, and is indexed among
+            # only the siblings that also match S.
+            return false unless matches?(element, anb.of, cache: cache, state: state)
+
+            nth_index_matching(element, anb.of, from_end:, cache:, state:)
+          else
+            nth_index(element, of_type:, from_end:)
+          end
 
         return false if index.nil?
 
@@ -307,6 +535,24 @@ module CSS
         idx && idx + 1
       end
 
+      # Index of `element` (1-based) counting only the siblings that match the
+      # `of S` selector list — used by `:nth-child(An+B of S)`.
+      def nth_index_matching(element, selector_list, from_end:, cache:, state:)
+        return nil if parent_element(element).nil?
+
+        direction = from_end ? :next_element : :previous_element
+        count     = 0
+        sib       = send(direction, element)
+
+        while sib
+          count += 1 if matches?(sib, selector_list, cache: cache, state: state)
+
+          sib = send(direction, sib)
+        end
+
+        count + 1
+      end
+
       # Form / link state -----------------------------------------------
 
       def link?(element)
@@ -400,6 +646,73 @@ module CSS
         v.nil? || v.empty?
       end
 
+      # `:default` — a selected option, a checked checkbox / radio, or a
+      # form's first submit button. Computed structurally (no host state).
+      def default?(element)
+        case tag(element)
+        when 'option'
+          !attr(element, 'selected').nil?
+        when 'input'
+          type = attr(element, 'type').to_s.downcase
+
+          if type == 'checkbox' || type == 'radio'
+            !attr(element, 'checked').nil?
+          else
+            submit_button?(element) && default_submit?(element)
+          end
+        when 'button'
+          submit_button?(element) && default_submit?(element)
+        else
+          false
+        end
+      end
+
+      def submit_button?(element)
+        case tag(element)
+        when 'button'
+          # `<button>`'s type is enumerated with Submit as both the missing-
+          # and invalid-value default, so it is a submit button unless it is
+          # explicitly `reset` or `button` (`type=""` / `type="x"` are submit).
+          type = attr(element, 'type').to_s.downcase
+          type != 'reset' && type != 'button'
+        when 'input'
+          type = attr(element, 'type').to_s.downcase
+          type == 'submit' || type == 'image'
+        else
+          false
+        end
+      end
+
+      def default_submit?(element)
+        form     = nil
+        ancestor = parent_element(element)
+
+        while ancestor
+          if tag(ancestor) == 'form'
+            form = ancestor
+            break
+          end
+
+          ancestor = parent_element(ancestor)
+        end
+
+        !form.nil? && same_node?(first_submit(form), element)
+      end
+
+      def first_submit(node)
+        element_children(node).each do |child|
+          return child if submit_button?(child)
+
+          # A nested <form>'s controls belong to that form, not this one.
+          next if tag(child) == 'form'
+
+          found = first_submit(child)
+          return found if found
+        end
+
+        nil
+      end
+
       def match_lang(element, argument)
         target = ident_argument(argument)
 
@@ -450,10 +763,19 @@ module CSS
         token&.value
       end
 
-      # CSS3 :empty semantics — element children always disqualify;
-      # whitespace-only text content does not. Comments / PIs / doctypes
-      # are ignored.
-      def empty?(element)
+      def empty_allows_whitespace?(state)
+        return true if state.nil?
+
+        v = state[EMPTY_WS_KEY]
+        v.nil? ? true : v
+      end
+
+      # `:empty` — element children always disqualify; comments / PIs /
+      # doctypes are ignored in both modes. Text content disqualifies per
+      # `allow_ws`: when true (Selectors-4 default) only non-whitespace text
+      # disqualifies (so `<p> </p>` is :empty); when false (real browsers /
+      # Selectors-3) any non-empty text does.
+      def empty?(element, allow_ws)
         return false unless element.respond_to?(:children)
 
         element.children.each do |child|
@@ -462,8 +784,8 @@ module CSS
           end
 
           if child.respond_to?(:text?) && child.text?
-            content = child.respond_to?(:content) ? child.content : child.text
-            return false if content.to_s.match?(/\S/)
+            content = (child.respond_to?(:content) ? child.content : child.text).to_s
+            return false if allow_ws ? content.match?(/\S/) : !content.empty?
           end
         end
 

data/lib/css/selectors/nodes.rb

@@ -24,8 +24,20 @@ module CSS
       def to_s = Selectors::Serializer.serialize(self)
     end
 
-    TypeSelector      = Data.define(:name)        { include Node }
-    UniversalSelector = Data.define              { include Node }
+    # `namespace` is the namespace constraint: `nil` (no prefix — any
+    # namespace), `'*'` (`*|name`, any), or `''` (`|name`, no namespace). A
+    # declared prefix (`svg|name`) is rejected at parse time — there is no
+    # `@namespace` mechanism.
+    TypeSelector = Data.define(:name, :namespace) do
+      include Node
+      def initialize(name:, namespace: nil) = super
+    end
+
+    UniversalSelector = Data.define(:namespace) do
+      include Node
+      def initialize(namespace: nil) = super
+    end
+
     NestingSelector   = Data.define              { include Node }
     IdSelector        = Data.define(:name)        { include Node }
     ClassSelector     = Data.define(:name)        { include Node }
@@ -39,9 +51,14 @@ module CSS
     #   :suffix     — `[a$=b]`
     #   :substring  — `[a*=b]`
     #
-    # `case_flag` is `nil`, `:i`, or `:s`.
-    AttributeSelector = Data.define(:name, :matcher, :value, :case_flag) do
+    # `case_flag` is `nil`, `:i`, or `:s`. `namespace` is the attribute
+    # namespace constraint (`nil` = no prefix, `'*'` = any, `''` = no
+    # namespace); a declared prefix is rejected. Attribute namespaces aren't
+    # tracked at match time (HTML attributes are all in no namespace), so
+    # matching is by local name.
+    AttributeSelector = Data.define(:name, :matcher, :value, :case_flag, :namespace) do
       include Node
+      def initialize(name:, matcher:, value:, case_flag:, namespace: nil) = super
     end
 
     # `argument` is `nil`, a `SelectorList` (`:not/:is/:where/:has`), an
@@ -52,8 +69,30 @@ module CSS
 
     # `An+B` integer pair. `step` is the `n` coefficient, `offset` is the
     # constant term. `even` => AnB(2, 0), `odd` => AnB(2, 1), `5` => AnB(0, 5),
-    # `n` => AnB(1, 0).
-    AnB = Data.define(:step, :offset) do
+    # `n` => AnB(1, 0). `of` is the optional `of S` filter (a `SelectorList`),
+    # `nil` except on `:nth-child` / `:nth-last-child`.
+    AnB = Data.define(:step, :offset, :of) do
+      include Node
+
+      def initialize(step:, offset:, of: nil)
+        super
+      end
+
+      def to_s = Selectors::Serializer.serialize(self)
+    end
+
+    # The argument of `:has()` — a comma-separated list of relative selectors.
+    RelativeSelectorList = Data.define(:selectors) do
+      include Node
+      def to_s = Selectors::Serializer.serialize(self)
+    end
+
+    # One relative selector: an (optionally explicit) leading combinator
+    # relative to the `:has()` anchor, then a complex selector. `combinator`
+    # is `:descendant` (the implicit default, `:has(.x)`), `:child`
+    # (`:has(> .x)`), `:next_sibling` (`:has(+ .x)`), or `:subsequent_sibling`
+    # (`:has(~ .x)`).
+    RelativeSelector = Data.define(:combinator, :complex) do
       include Node
       def to_s = Selectors::Serializer.serialize(self)
     end

data/lib/css/selectors/parser.rb

@@ -4,21 +4,32 @@ module CSS
     # selectors, the four standard combinators (descendant, child, next-
     # sibling, subsequent-sibling), pseudo-classes / pseudo-elements
     # (with recursive parsing of `:not/:is/:where/:has` and AnB parsing of
-    # `:nth-*`), attribute selectors with case-insensitive `i` / `s` flags,
-    # and the `&` nesting selector.
+    # `:nth-*`, including `An+B of S`), attribute selectors with case-
+    # insensitive `i` / `s` flags, the `&` nesting selector, and namespace
+    # prefixes (`*|name`, `|name`; a declared prefix is rejected — there is no
+    # `@namespace` support).
     #
-    # Out of scope (intermediate plan): namespace prefixes, the column
-    # combinator `||`, and forgiving vs strict selector list distinctions.
+    # Out of scope: the column combinator `||`, and forgiving vs strict
+    # selector list distinctions.
     class Parser
       include CSS::TokenCursor
 
-      # `:has()` is intentionally excluded — it takes a *relative* selector
-      # list (each item may start with a combinator) which would require
-      # extending the ComplexSelector AST. Falls back to opaque component
-      # values for now.
       SELECTOR_LIST_PSEUDOS = %w[is where not matches].freeze
       ANB_PSEUDOS           = %w[nth-child nth-last-child nth-of-type nth-last-of-type].freeze
 
+      # Per the Selectors grammar (and every browser's querySelector), a known
+      # pseudo-element is a valid selector that simply matches no element, while
+      # an unknown one (`::example`) is a syntax error. Vendor-prefixed
+      # `::-webkit-…` are accepted leniently since they match nothing.
+      KNOWN_PSEUDO_ELEMENTS = %w[
+        before after first-line first-letter
+        marker placeholder selection backdrop file-selector-button
+        target-text grammar-error spelling-error highlight
+        cue cue-region part slotted details-content
+        view-transition view-transition-group view-transition-image-pair
+        view-transition-old view-transition-new
+      ].to_set.freeze
+
       ATTR_MATCHERS = {
         '~' => :includes,
         '|' => :dash,
@@ -36,6 +47,14 @@ module CSS
           new(tokens_from(input)).parse_selector_complete
         end
 
+        # Like `parse_selector_list`, but each complex selector may begin with
+        # a combinator (`>` / `+` / `~`), synthesising a leading `&`. Used for
+        # CSS Nesting nested rules, whose preludes follow the
+        # `<relative-selector-list>` grammar.
+        def parse_nesting_selector_list(input)
+          new(tokens_from(input)).parse_nesting_selector_list_complete
+        end
+
         private
 
         def tokens_from(input)
@@ -140,6 +159,58 @@ module CSS
         ComplexSelector.new(compounds:, combinators:)
       end
 
+      def parse_nesting_selector_list_complete
+        list = parse_nesting_selector_list
+
+        skip_whitespace
+
+        parse_error!("trailing tokens after selector list: #{peek.type}") unless peek.type == :eof
+
+        list
+      end
+
+      def parse_nesting_selector_list
+        skip_whitespace
+
+        parse_error!('empty selector list') if list_terminator?(peek)
+
+        selectors = [parse_nesting_complex_selector]
+
+        loop do
+          skip_whitespace
+          break unless peek.type == :comma
+
+          consume
+          skip_whitespace
+          selectors << parse_nesting_complex_selector
+        end
+
+        SelectorList.new(selectors:)
+      end
+
+      # A nested-rule complex selector may start with a combinator, which
+      # implies a leading `&` (`> .c` → `& > .c`), preserving the
+      # `compounds == combinators + 1` invariant.
+      def parse_nesting_complex_selector
+        skip_whitespace
+
+        t = peek
+
+        if t.type == :delim && (combo = combinator_for_delim(t.value))
+          consume
+          skip_whitespace
+
+          rest = parse_complex_selector
+
+          return ComplexSelector.new(
+            compounds:   [CompoundSelector.new(components: [NestingSelector.new]), *rest.compounds],
+            combinators: [combo, *rest.combinators]
+          )
+        end
+
+        parse_complex_selector
+      end
+
       private
 
       def consume_whitespace_returning_bool
@@ -190,7 +261,7 @@ module CSS
         when :ident, :hash, :lbracket, :colon
           true
         when :delim
-          %w[* . &].include?(t.value)
+          %w[* . & |].include?(t.value)
         else
           false
         end
@@ -215,16 +286,53 @@ module CSS
         CompoundSelector.new(components:)
       end
 
+      # Consumes an optional namespace prefix (`*|`, `|`, or `prefix|`) and
+      # returns the namespace: `'*'` (any), `''` (no namespace), or `nil` when
+      # there is no prefix (nothing consumed). A declared prefix (`svg|`) is
+      # invalid — there is no `@namespace` mechanism — so it raises.
+      def try_consume_namespace_prefix
+        t = peek
+
+        # `ident|` or `*|` (immediately, not `…|=` which is an attribute matcher).
+        if (t.type == :ident || (t.type == :delim && t.value == '*')) &&
+           peek(1).type == :delim && peek(1).value == '|' &&
+           peek(2).value != '='
+          parse_error!("undeclared namespace prefix '#{t.value}'") if t.type == :ident
+
+          consume # *
+          consume # |
+          return '*'
+        end
+
+        # Leading `|` — the no-namespace prefix (not `|=`).
+        if t.type == :delim && t.value == '|' && peek(1).value != '='
+          consume # |
+          return ''
+        end
+
+        nil
+      end
+
       def try_consume_type_or_universal
+        ns = try_consume_namespace_prefix
+
         case peek.type
         when :ident
-          TypeSelector.new(name: consume.value)
+          return TypeSelector.new(name: consume.value, namespace: ns)
         when :delim
-          case peek.value
-          when '*' then consume; UniversalSelector.new
-          when '&' then consume; NestingSelector.new
+          if peek.value == '*'
+            consume
+            return UniversalSelector.new(namespace: ns)
           end
         end
+
+        # A consumed prefix must be followed by a name or `*`.
+        parse_error!("expected element name or '*' after namespace prefix") unless ns.nil?
+
+        if peek.type == :delim && peek.value == '&'
+          consume
+          NestingSelector.new
+        end
       end
 
       def try_consume_subclass_or_pseudo
@@ -263,6 +371,8 @@ module CSS
         consume # [
         skip_whitespace
 
+        namespace = try_consume_namespace_prefix
+
         parse_error!('expected attribute name') unless peek.type == :ident
 
         name = consume.value
@@ -278,7 +388,7 @@ module CSS
 
         consume
 
-        AttributeSelector.new(name:, matcher:, value:, case_flag:)
+        AttributeSelector.new(name:, matcher:, value:, case_flag:, namespace:)
       end
 
       def parse_attr_matcher_and_value
@@ -332,21 +442,31 @@ module CSS
       end
 
       def parse_pseudo_body(element:)
-        case peek.type
-        when :ident
-          name = consume.value
-          build_pseudo(element:, name:, argument: nil)
-        when :function
-          name = consume.value
-          arg  = parse_pseudo_argument(name)
+        head = peek.type
+
+        unless head == :ident || head == :function
+          parse_error!("expected pseudo-#{element ? 'element' : 'class'} name, got #{head}")
+        end
 
-          parse_error!("expected ')' to close :#{name}") unless peek.type == :rparen
+        name = consume.value
 
-          consume
-          build_pseudo(element:, name:, argument: arg)
-        else
-          parse_error!("expected pseudo-#{element ? 'element' : 'class'} name, got #{peek.type}")
+        if element && !known_pseudo_element?(name)
+          parse_error!("unknown pseudo-element ::#{name}")
         end
+
+        return build_pseudo(element:, name:, argument: nil) if head == :ident
+
+        arg = parse_pseudo_argument(name)
+
+        parse_error!("expected ')' to close :#{name}") unless peek.type == :rparen
+
+        consume
+        build_pseudo(element:, name:, argument: arg)
+      end
+
+      def known_pseudo_element?(name)
+        n = name.downcase
+        n.start_with?('-') || KNOWN_PSEUDO_ELEMENTS.include?(n)
       end
 
       def build_pseudo(element:, name:, argument:)
@@ -358,13 +478,87 @@ module CSS
 
         if SELECTOR_LIST_PSEUDOS.include?(n)
           parse_selector_list
+        elsif n == 'has'
+          parse_relative_selector_list
         elsif ANB_PSEUDOS.include?(n)
-          AnBParser.parse(collect_argument_tokens)
+          parse_nth_argument(allow_of: n == 'nth-child' || n == 'nth-last-child')
         else
           collect_argument_tokens
         end
       end
 
+      # `:nth-*` argument: An+B, optionally followed by `of <selector-list>`
+      # (Selectors-4, only on `:nth-child` / `:nth-last-child`). Collects the
+      # An+B tokens up to a top-level `of` ident, then parses S inline.
+      def parse_nth_argument(allow_of:)
+        anb_tokens = []
+        depth      = 0
+
+        loop do
+          t = peek
+
+          parse_error!('unexpected EOF in :nth argument') if t.type == :eof
+
+          if depth.zero?
+            break if t.type == :rparen
+            break if allow_of && t.type == :ident && t.value.downcase == 'of'
+          end
+
+          case t.type
+          when :function, :lparen then depth += 1
+          when :rparen            then depth -= 1
+          end
+
+          anb_tokens << consume
+        end
+
+        anb = AnBParser.parse(anb_tokens)
+
+        return anb unless allow_of && peek.type == :ident && peek.value.downcase == 'of'
+
+        consume # `of`
+        skip_whitespace
+        AnB.new(step: anb.step, offset: anb.offset, of: parse_selector_list)
+      end
+
+      # `:has()` argument: a comma-separated list of relative selectors, each
+      # an optional leading combinator (`>`, `+`, `~`; default descendant)
+      # followed by a complex selector. Terminated by EOF or the closing `)`.
+      def parse_relative_selector_list
+        skip_whitespace
+
+        parse_error!('empty :has() argument') if list_terminator?(peek)
+
+        selectors = [parse_relative_selector]
+
+        loop do
+          skip_whitespace
+          break unless peek.type == :comma
+
+          consume
+          skip_whitespace
+          selectors << parse_relative_selector
+        end
+
+        RelativeSelectorList.new(selectors:)
+      end
+
+      def parse_relative_selector
+        skip_whitespace
+
+        combinator = :descendant
+
+        t = peek
+
+        if t.type == :delim && (combo = combinator_for_delim(t.value))
+          combinator = combo
+          consume
+          skip_whitespace
+        end
+
+        RelativeSelector.new(combinator:, complex: parse_complex_selector)
+      end
+
       # Collects all tokens up to the closing `)` of the current functional
       # context, balancing nested parens / functions.
       def collect_argument_tokens

data/lib/css/selectors/serializer.rb

@@ -10,6 +10,15 @@ module CSS
         subsequent_sibling:  ' ~ '
       }.freeze
 
+      # Leading combinator of a `:has()` relative selector (descendant is
+      # implicit, so it has no prefix).
+      LEADING_COMBINATOR_GLUE = {
+        descendant:          '',
+        child:               '> ',
+        next_sibling:        '+ ',
+        subsequent_sibling:  '~ '
+      }.freeze
+
       ATTR_OPS = {
         exact:     '=',
         includes:  '~=',
@@ -24,15 +33,17 @@ module CSS
         when SelectorList      then node.selectors.map { serialize(_1) }.join(', ')
         when ComplexSelector   then serialize_complex(node)
         when CompoundSelector  then node.components.map { serialize(_1) }.join
-        when TypeSelector      then Escape.ident(node.name)
-        when UniversalSelector then '*'
+        when TypeSelector      then ns_prefix(node.namespace) + Escape.ident(node.name)
+        when UniversalSelector then "#{ns_prefix(node.namespace)}*"
         when NestingSelector   then '&'
         when IdSelector        then "##{Escape.ident(node.name)}"
         when ClassSelector     then ".#{Escape.ident(node.name)}"
         when AttributeSelector then serialize_attribute(node)
-        when PseudoClass       then serialize_pseudo(node, '')
-        when PseudoElement     then serialize_pseudo(node, ':')
-        when AnB               then serialize_anb(node)
+        when PseudoClass          then serialize_pseudo(node, '')
+        when PseudoElement        then serialize_pseudo(node, ':')
+        when AnB                  then serialize_anb(node)
+        when RelativeSelectorList then node.selectors.map { serialize_relative(_1) }.join(', ')
+        when RelativeSelector     then serialize_relative(node)
         else
           raise ArgumentError, "cannot serialize selector node #{node.class}"
         end
@@ -40,6 +51,10 @@ module CSS
 
       private
 
+      def serialize_relative(rel)
+        LEADING_COMBINATOR_GLUE.fetch(rel.combinator) + serialize(rel.complex)
+      end
+
       def serialize_complex(cs)
         out = +serialize(cs.compounds[0])
 
@@ -50,8 +65,16 @@ module CSS
         out
       end
 
+      def ns_prefix(namespace)
+        case namespace
+        when '*' then '*|'
+        when ''  then '|'
+        else          ''
+        end
+      end
+
       def serialize_attribute(attr)
-        out = +"[#{Escape.ident(attr.name)}"
+        out = +"[#{ns_prefix(attr.namespace)}#{Escape.ident(attr.name)}"
 
         if attr.matcher
           out << ATTR_OPS.fetch(attr.matcher) << Escape.string(attr.value.to_s)
@@ -71,15 +94,22 @@ module CSS
 
       def serialize_argument(arg)
         case arg
-        when SelectorList then serialize(arg)
-        when AnB          then serialize_anb(arg)
-        when Array        then CSS::Serializer.serialize(arg)
+        when SelectorList         then serialize(arg)
+        when RelativeSelectorList then serialize(arg)
+        when AnB                  then serialize_anb(arg)
+        when Array                then CSS::Serializer.serialize(arg)
         else
           raise ArgumentError, "unknown pseudo argument #{arg.class}"
         end
       end
 
       def serialize_anb(anb)
+        out = serialize_anb_value(anb)
+        out += " of #{serialize(anb.of)}" if anb.of
+        out
+      end
+
+      def serialize_anb_value(anb)
         return 'even' if anb.step == 2 && anb.offset.zero?
         return 'odd'  if anb.step == 2 && anb.offset == 1
 

data/lib/css/selectors/specificity.rb

@@ -66,12 +66,26 @@ module CSS
         case node.name.downcase
         when 'where'
           Specificity::ZERO
-        when 'is', 'not', 'has', 'matches'
+        when 'has'
+          # `:has()` contributes the most specific complex selector in its
+          # relative-selector-list argument (like `:is`).
+          if node.argument.is_a?(RelativeSelectorList)
+            node.argument.selectors.map { calculate(_1.complex) }.max || Specificity.new(a: 0, b: 1, c: 0)
+          else
+            Specificity.new(a: 0, b: 1, c: 0)
+          end
+        when 'is', 'not', 'matches'
           if node.argument.is_a?(SelectorList)
             calculate(node.argument)
           else
             Specificity.new(a: 0, b: 1, c: 0)
           end
+        when 'nth-child', 'nth-last-child'
+          # `(0,1,0)` plus, for the `of S` form, the most specific complex
+          # selector in S.
+          base = Specificity.new(a: 0, b: 1, c: 0)
+          of   = node.argument.is_a?(AnB) ? node.argument.of : nil
+          of.is_a?(SelectorList) ? base + calculate(of) : base
         else
           Specificity.new(a: 0, b: 1, c: 0)
         end

data/lib/css/tokenizer.rb

@@ -183,9 +183,11 @@ module CSS
       o <= 0x08 || o == 0x0B || (0x0E..0x1F).cover?(o) || o == 0x7F
     end
 
-    # §4.3.8.
+    # §4.3.8: `\` is a valid escape unless followed by a newline. EOF (c2 is
+    # nil) is NOT a newline, so `\` at end-of-input is a valid escape — it
+    # consumes to U+FFFD (§4.3.7), e.g. `#eof\` is the id `#eof␦`.
     def valid_escape?(c1, c2)
-      c1 == '\\' && c2 != "\n" && !c2.nil?
+      c1 == '\\' && c2 != "\n"
     end
 
     # §4.3.9.
@@ -322,7 +324,9 @@ module CSS
         @pos += 1
       end
 
-      return @chars[start, @pos - start].join unless c == '\\' && (n = @chars[@pos + 1]) && n != "\n"
+      # Inline valid_escape?: `\` is a valid escape unless followed by a
+      # newline; EOF (@chars[@pos + 1] is nil) is a valid escape → U+FFFD.
+      return @chars[start, @pos - start].join unless c == '\\' && @chars[@pos + 1] != "\n"
 
       buf = @chars[start, @pos - start].join.dup
       @pos += 1
@@ -334,7 +338,7 @@ module CSS
         if o >= 128 || IDENT_CP_TABLE[o]
           buf << c
           @pos += 1
-        elsif c == '\\' && (n = @chars[@pos + 1]) && n != "\n"
+        elsif c == '\\' && @chars[@pos + 1] != "\n"
           @pos += 1
           buf << consume_escaped_code_point
         else

data/lib/css/version.rb

@@ -1,3 +1,3 @@
 module CSS
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/css.rb

@@ -50,7 +50,21 @@ module CSS
 
     def specificity(selector) = Selectors::SpecificityCalculator.calculate(selector)
 
-    def matches?(element, selector, state: nil) = Selectors::Matcher.matches?(element, selector, state: state)
+    def matches?(element, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+      Selectors::Matcher.matches?(element, selector, state:, scope:, empty_allows_whitespace:)
+    end
+
+    def select_all(roots, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+      Selectors::Matcher.select_all(roots, selector, state:, scope:, empty_allows_whitespace:)
+    end
+
+    def select_first(roots, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+      Selectors::Matcher.select_first(roots, selector, state:, scope:, empty_allows_whitespace:)
+    end
+
+    def closest(element, selector, state: nil, scope: nil, empty_allows_whitespace: true)
+      Selectors::Matcher.closest(element, selector, state:, scope:, empty_allows_whitespace:)
+    end
 
     def parse_media_query_list(input) = MediaQueries::Parser.parse(input)
 

data/sig/css/selectors.rbs

@@ -17,11 +17,14 @@ module CSS
     type case_flag = :i | :s
 
     # `argument` is `nil` for plain `:hover` etc., a `SelectorList` for
-    # `:not / :is / :where / :matches`, an `AnB` for `:nth-*`, or an
-    # opaque component-value array for unrecognized functional pseudos
-    # (including `:has`, which is intentionally not parsed as a selector
-    # list yet).
-    type pseudo_argument = nil | SelectorList | AnB | Array[component_value]
+    # `:not / :is / :where / :matches`, a `RelativeSelectorList` for `:has`,
+    # an `AnB` for `:nth-*`, or an opaque component-value array for
+    # unrecognized functional pseudos.
+    type pseudo_argument = nil | SelectorList | RelativeSelectorList | AnB | Array[component_value]
+
+    # Namespace constraint: `nil` (no prefix — any namespace), `'*'` (any),
+    # or `''` (no namespace).
+    type namespace = String?
 
     class SelectorList < Data
       include Node
@@ -60,14 +63,17 @@ module CSS
       include Node
 
       attr_reader name: String
+      attr_reader namespace: namespace
 
-      def self.new: (name: String) -> TypeSelector
+      def self.new: (name: String, ?namespace: namespace) -> TypeSelector
     end
 
     class UniversalSelector < Data
       include Node
 
-      def self.new: () -> UniversalSelector
+      attr_reader namespace: namespace
+
+      def self.new: (?namespace: namespace) -> UniversalSelector
     end
 
     class NestingSelector < Data
@@ -99,8 +105,9 @@ module CSS
       attr_reader matcher: attribute_matcher?
       attr_reader value: String?
       attr_reader case_flag: case_flag?
+      attr_reader namespace: namespace
 
-      def self.new: (name: String, matcher: attribute_matcher?, value: String?, case_flag: case_flag?) -> AttributeSelector
+      def self.new: (name: String, matcher: attribute_matcher?, value: String?, case_flag: case_flag?, ?namespace: namespace) -> AttributeSelector
     end
 
     class PseudoClass < Data
@@ -126,8 +133,34 @@ module CSS
 
       attr_reader step: Integer
       attr_reader offset: Integer
+      attr_reader of: SelectorList?
+
+      def self.new: (step: Integer, offset: Integer, ?of: SelectorList?) -> AnB
+
+      def to_s: () -> String
+    end
+
+    # The argument of `:has()` — a list of relative selectors.
+    class RelativeSelectorList < Data
+      include Node
+
+      attr_reader selectors: Array[RelativeSelector]
 
-      def self.new: (step: Integer, offset: Integer) -> AnB
+      def self.new: (selectors: Array[RelativeSelector]) -> RelativeSelectorList
+
+      def to_s: () -> String
+    end
+
+    # One relative selector: a leading combinator (`:descendant` default,
+    # `:child`, `:next_sibling`, `:subsequent_sibling`) plus a complex
+    # selector.
+    class RelativeSelector < Data
+      include Node
+
+      attr_reader combinator: combinator
+      attr_reader complex: ComplexSelector
+
+      def self.new: (combinator: combinator, complex: ComplexSelector) -> RelativeSelector
 
       def to_s: () -> String
     end
@@ -154,7 +187,11 @@ module CSS
       STATEFUL_PSEUDOS: Set[String]
       PROPAGATING_STATEFUL_PSEUDOS: Set[String]
 
-      def self.matches?: (untyped element, untyped selector, ?cache: Hash[Integer, untyped], ?state: matcher_state?) -> bool
+      def self.matches?: (untyped element, untyped selector, ?cache: Hash[Integer, untyped], ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> bool
+
+      def self.select_all: (untyped roots, untyped selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> Array[untyped]
+      def self.select_first: (untyped roots, untyped selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> untyped
+      def self.closest: (untyped element, untyped selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> untyped
 
       def self.tag_of: (untyped element, ?Hash[Integer, untyped]?) -> String
       def self.id_of: (untyped element, ?Hash[Integer, untyped]?) -> String?

data/sig/css.rbs

@@ -73,7 +73,16 @@ module CSS
   # specific elements in that state, or falsy (no match).
   type matcher_state = Hash[Symbol | String, bool | Set[untyped] | Array[untyped]]
 
-  def self.matches?: (untyped element, String | selector selector, ?cache: Hash[Integer, untyped], ?state: matcher_state?) -> bool
+  # The set `:scope` matches: a single element, or an Array / Set of them.
+  type scope = untyped | Array[untyped] | Set[untyped]
+
+  def self.matches?: (untyped element, String | selector selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> bool
+
+  # querySelector-style tree queries over the descendants of `roots` (an
+  # element or array of elements). `closest` walks inclusive ancestors.
+  def self.select_all: (untyped roots, String | selector selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> Array[untyped]
+  def self.select_first: (untyped roots, String | selector selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> untyped
+  def self.closest: (untyped element, String | selector selector, ?state: matcher_state?, ?scope: scope?, ?empty_allows_whitespace: bool) -> untyped
 
   # Media queries (Media Queries 4)
   # ---------------------------------------------------------------

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p_css
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Keita Urashima