p_css 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 965047de25f5fe1719b2d2b4c59d2fa2d74550249e2ffa23d4175ae88dc09ba9
-  data.tar.gz: ab8078d7209427b3f23cd774492fae69543bd8910b812a1a87fc7da38b8df89c
+  metadata.gz: 99fe89569a8cb686b5fa018e7403b55ba6603a46ccad4a8df4821135579b6ada
+  data.tar.gz: 8474073401ef004e365a6e294dcf35c92338ad6c4688168e999fccecac6a95e5
 SHA512:
-  metadata.gz: '069d1c89de282155ee708b19aee7cc61226a68bd7ad662a869536b823bb99d58c6b8b1dae2567fa9f27d337fda392ea52f62592a718580aead69e1ded17cbf47'
-  data.tar.gz: 2d0ec3fd003f145859790f3140ec808e5ba1d1273dc2e78e379d7ef5eec3dd44c9c031cd8e5db22f5b1b63b27d52f9973cc18f19b0f184ebd6a882d73b24ac36
+  metadata.gz: 7c79fcc55da6b57149893332f9d491912f66d04d8a2f6d6ffef9f57fb30872ecf22b00b4184730088fbcc92639bf7d55204c075147b78174f2f5e48d057f9ba8
+  data.tar.gz: efb733700697de31e950e90b35f10597d22975c3e0ae64ed8575474c0da175bd80bed92c39eedd3a3154560a0b7a604c79eeb3cb0ccec3b785429d7705918346

data/README.md

@@ -61,7 +61,7 @@ Or:
 bundle add p_css
 ```
 
-Ruby 3.4+ is required. The matcher works against any object that quacks like
+Ruby 3.3+ is required. The matcher works against any object that quacks like
 a DOM element (`Nokogiri::XML::Element` works out of the box); Nokogiri is not
 a hard dependency.
 
@@ -185,8 +185,9 @@ CSS.matches?(active, 'ul > li:not(:first-child)')        # => true
 ```
 
 Stateful pseudo-classes (`:hover`, `:focus`, `:visited`, validity API states,
-etc.) deliberately return `false` — this matcher is intended for stateless
-analysis. `:has()` is not yet implemented (its argument is kept as opaque
+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).
 
 ### Nesting de-sugar
@@ -270,6 +271,60 @@ source order. Cascade layers, `@scope` proximity, and Shadow DOM
 encapsulation are not modeled — `@layer` / `@supports` / `@scope` /
 `@container` / `@starting-style` blocks are descended into unconditionally.
 
+### 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:
+
+```ruby
+state = {
+  hover:           Set[hovered_element],   # match these and their ancestors
+  focus:           Set[focused_element],   # match only this element
+  'focus-within' => Set[el],               # propagates to ancestors
+  active:          true                    # match every element
+}
+
+CSS.matches?(element, ':hover', state: state)
+cascade.resolve(element, state: state)
+```
+
+Values:
+
+- `Set` or `Array` of elements — matches those elements (and, for
+  `:hover`, `:active`, `:focus-within`, their ancestors per Selectors §10)
+- `true` — matches every element
+- falsy / missing — default behavior; never matches
+
+Symbol and String keys are both accepted. Hyphenated names (`focus-within`,
+`focus-visible`) read more naturally as String keys.
+
+#### Limits of stateful matching
+
+The API gives you the primitives but not a policy. Two patterns are
+inherently hard:
+
+- **`hover: true` over-reveals.** Every `:hover`-gated rule matches every
+  element, so multiple dropdowns / popovers / menus all become "visible"
+  simultaneously. Useful for "is this element *potentially* visible
+  somehow?" but not for unique-match queries.
+
+- **Peer-row reveal patterns are unsolvable without mouse position.**
+  Stylesheets like `.row:hover .icon-copy { display: block }` reveal one
+  icon per row when its row is hovered. Per-candidate evaluation (giving
+  each candidate its own ancestor chain in the hover Set) doesn't break
+  the symmetry — every candidate sees its own `.row` ancestor as hovered
+  and reports itself visible. Real browsers disambiguate via the actual
+  mouse position; a headless analyzer can't reproduce that without the
+  test explicitly recording which element it treats as hovered (e.g. via
+  Capybara's `element.hover`).
+
+The recommendation for tools layered on top of p CSS: track explicit hover
+actions and pass the corresponding Set; for queries that depend on
+hover-based uniqueness without an explicit hover, treat them as fragile
+and disambiguate by `text:` / `id:` / data attributes instead of relying
+on stateful CSS.
+
 ### `urange`
 
 ```ruby
@@ -295,7 +350,7 @@ These are deliberate omissions; pull requests welcome:
 
 ## Compatibility
 
-Ruby 3.4+. Tested on the current MRI. No mandatory runtime dependencies.
+Ruby 3.3+. Tested on the current MRI. No mandatory runtime dependencies.
 
 ## License
 

data/lib/css/cascade.rb

@@ -89,11 +89,11 @@ module CSS
     end
 
     def register_qualified_rule(rule, media_chain, out)
-      return unless media_chain.all? { MediaQueries::Evaluator.evaluate(it, @context) }
+      return unless media_chain.all? { MediaQueries::Evaluator.evaluate(_1, @context) }
 
       sl    = Selectors::Parser.parse_selector_list(rule.prelude)
-      pairs = sl.selectors.map { [it, Selectors::SpecificityCalculator.calculate(it)] }
-      decls = rule.block.items.select { it.is_a?(Nodes::Declaration) }
+      pairs = sl.selectors.map { [_1, Selectors::SpecificityCalculator.calculate(_1)] }
+      decls = rule.block.items.select { _1.is_a?(Nodes::Declaration) }
 
       out << RuleEntry.new(selector_pairs: pairs, declarations: decls)
     rescue ParseError
@@ -259,9 +259,9 @@ module CSS
 
     def inline_declarations(style)
       case style
-      when String       then CSS.parse_block_contents(style).items.select { it.is_a?(Nodes::Declaration) }
-      when Nodes::Block then style.items.select { it.is_a?(Nodes::Declaration) }
-      when Array        then style.select        { it.is_a?(Nodes::Declaration) }
+      when String       then CSS.parse_block_contents(style).items.select { _1.is_a?(Nodes::Declaration) }
+      when Nodes::Block then style.items.select { _1.is_a?(Nodes::Declaration) }
+      when Array        then style.select        { _1.is_a?(Nodes::Declaration) }
       else
         raise ArgumentError, "cannot derive inline declarations from #{style.class}"
       end

data/lib/css/code_points.rb

@@ -14,7 +14,7 @@ module CSS
     def self.build_table(*ranges_or_ints)
       Array.new(128, false).tap {|a|
         ranges_or_ints.each {|r|
-          if r.is_a?(Range) then r.each { a[it] = true }
+          if r.is_a?(Range) then r.each { a[_1] = true }
           else                   a[r] = true
           end
         }

data/lib/css/media_queries/evaluator.rb

@@ -38,7 +38,7 @@ module CSS
       PREFIX_OP = {min: :ge, max: :le}.freeze
 
       def evaluate(query_list, context)
-        query_list.queries.any? { evaluate_query(it, context) }
+        query_list.queries.any? { evaluate_query(_1, context) }
       end
 
       private
@@ -65,8 +65,8 @@ module CSS
       def evaluate_condition(node, context)
         case node
         when MediaNot       then !evaluate_condition(node.operand, context)
-        when MediaAnd       then node.operands.all? { evaluate_condition(it, context) }
-        when MediaOr        then node.operands.any? { evaluate_condition(it, context) }
+        when MediaAnd       then node.operands.all? { evaluate_condition(_1, context) }
+        when MediaOr        then node.operands.any? { evaluate_condition(_1, context) }
         when MediaFeature   then evaluate_feature(node, context)
         when GeneralEnclosed then false
         else                      false

data/lib/css/nesting.rb

@@ -12,7 +12,7 @@ module CSS
     extend self
 
     def desugar(stylesheet)
-      Nodes::Stylesheet.new(rules: stylesheet.rules.flat_map { desugar_top_level(it) })
+      Nodes::Stylesheet.new(rules: stylesheet.rules.flat_map { desugar_top_level(_1) })
     end
 
     private
@@ -135,7 +135,7 @@ module CSS
 
     def contains_nesting?(complex_selector)
       complex_selector.compounds.any? {|c|
-        c.components.any? { it.is_a?(Selectors::NestingSelector) }
+        c.components.any? { _1.is_a?(Selectors::NestingSelector) }
       }
     end
 
@@ -159,7 +159,7 @@ module CSS
       replacement = Selectors::PseudoClass.new(name: 'is', argument: parent_list)
 
       Selectors::ComplexSelector.new(
-        compounds:   own_complex.compounds.map { swap_components_in_compound(it, replacement) },
+        compounds:   own_complex.compounds.map { swap_components_in_compound(_1, replacement) },
         combinators: own_complex.combinators
       )
     end

data/lib/css/parser.rb

@@ -207,8 +207,11 @@ module CSS
       AtRule.new(name:, prelude:, block:)
     end
 
+    # On EOF or a stop token (`}` while nested), the rule is dropped per
+    # §5.4.3 — but already-consumed prelude tokens are NOT put back. Rewinding
+    # would leave the caller's cursor at the same starting token and loop
+    # forever on input like `style="hidden"` (no `:` and no `{`).
     def consume_qualified_rule(nested:)
-      saved   = @pos
       prelude = []
 
       loop do
@@ -216,13 +219,9 @@ module CSS
 
         case t.type
         when :eof
-          @pos = saved
           return nil
         when :rbrace
-          if nested
-            @pos = saved
-            return nil
-          end
+          return nil if nested
 
           prelude << consume
         when :semicolon
@@ -321,7 +320,7 @@ module CSS
         end
       end
 
-      if value.any? { it.is_a?(SimpleBlock) && it.braced? }
+      if value.any? { _1.is_a?(SimpleBlock) && _1.braced? }
         @pos = saved
         return nil
       end

data/lib/css/selectors/matcher.rb

@@ -50,7 +50,7 @@ module CSS
 
         case sel
         when SelectorList
-          sel.selectors.any? { match_complex(element, it, cache, state) }
+          sel.selectors.any? { match_complex(element, _1, cache, state) }
         when ComplexSelector
           match_complex(element, sel, cache, state)
         when CompoundSelector
@@ -99,7 +99,7 @@ module CSS
       end
 
       def match_compound(element, compound, cache, state)
-        compound.components.all? { match_simple(element, it, cache, state) }
+        compound.components.all? { match_simple(element, _1, cache, state) }
       end
 
       def match_simple(element, simple, cache, state)
@@ -281,10 +281,10 @@ module CSS
         return nil if p.nil?
 
         siblings = element_children(p)
-        siblings = siblings.select { tag(it).casecmp?(tag(element)) } if of_type
+        siblings = siblings.select { tag(_1).casecmp?(tag(element)) } if of_type
         siblings = siblings.reverse if from_end
 
-        idx = siblings.index { same_node?(it, element) }
+        idx = siblings.index { same_node?(_1, element) }
         idx && idx + 1
       end
 
@@ -316,7 +316,7 @@ module CSS
       end
 
       def inside_first_legend?(element, fieldset)
-        first_legend = element_children(fieldset).find { tag(it) == 'legend' }
+        first_legend = element_children(fieldset).find { tag(_1) == 'legend' }
 
         return false if first_legend.nil?
 
@@ -427,7 +427,7 @@ module CSS
       def ident_argument(argument)
         return nil unless argument.is_a?(Array)
 
-        token = argument.find { it.is_a?(Token) && (it.type == :ident || it.type == :string) }
+        token = argument.find { _1.is_a?(Token) && (_1.type == :ident || _1.type == :string) }
         token&.value
       end
 

data/lib/css/selectors/serializer.rb

@@ -21,9 +21,9 @@ module CSS
 
       def serialize(node)
         case node
-        when SelectorList      then node.selectors.map { serialize(it) }.join(', ')
+        when SelectorList      then node.selectors.map { serialize(_1) }.join(', ')
         when ComplexSelector   then serialize_complex(node)
-        when CompoundSelector  then node.components.map { serialize(it) }.join
+        when CompoundSelector  then node.components.map { serialize(_1) }.join
         when TypeSelector      then Escape.ident(node.name)
         when UniversalSelector then '*'
         when NestingSelector   then '&'

data/lib/css/selectors/specificity.rb

@@ -41,7 +41,7 @@ module CSS
 
       def calculate(node)
         case node
-        when SelectorList     then node.selectors.map { calculate(it) }.max || Specificity::ZERO
+        when SelectorList     then node.selectors.map { calculate(_1) }.max || Specificity::ZERO
         when ComplexSelector  then sum(node.compounds)
         when CompoundSelector then sum(node.components)
         when IdSelector       then Specificity.new(a: 1, b: 0, c: 0)
@@ -59,7 +59,7 @@ module CSS
       private
 
       def sum(items)
-        items.map { calculate(it) }.reduce(Specificity::ZERO, :+)
+        items.map { calculate(_1) }.reduce(Specificity::ZERO, :+)
       end
 
       def specificity_of_pseudo_class(node)

data/lib/css/serializer.rb

@@ -21,7 +21,7 @@ module CSS
       when Nodes::SimpleBlock   then serialize_simple_block(node)
       when Token                then serialize_token(node)
       when Selectors::Node      then Selectors::Serializer.serialize(node)
-      when Array                then node.map { serialize(it) }.join
+      when Array                then node.map { serialize(_1) }.join
       else
         raise ArgumentError, "cannot serialize #{node.class}"
       end
@@ -30,7 +30,7 @@ module CSS
     private
 
     def serialize_stylesheet(ss)
-      ss.rules.map { serialize(it) }.join("\n")
+      ss.rules.map { serialize(_1) }.join("\n")
     end
 
     def serialize_at_rule(rule)
@@ -49,7 +49,7 @@ module CSS
     def serialize_block(block)
       return '{}' if block.items.empty?
 
-      inner = block.items.map { serialize(it) }.join("\n")
+      inner = block.items.map { serialize(_1) }.join("\n")
       "{\n#{indent(inner)}\n}"
     end
 
@@ -159,8 +159,8 @@ module CSS
     def serialize_string(s) = Escape.string(s)
 
     def indent(str)
-      str.lines.map { "#{INDENT}#{it}" }.join.then {
-        it.end_with?("\n") ? it.chomp : it
+      str.lines.map { "#{INDENT}#{_1}" }.join.then {
+        _1.end_with?("\n") ? _1.chomp : _1
       }
     end
   end

data/lib/css/token.rb

@@ -93,7 +93,7 @@ module CSS
     private
 
     def compute_position
-      idx     = @newlines.bsearch_index { it >= @start_offset } || @newlines.size
+      idx     = @newlines.bsearch_index { _1 >= @start_offset } || @newlines.size
       prev_nl = idx.zero? ? -1 : @newlines[idx - 1]
 
       Position.new(

data/lib/css/version.rb

@@ -1,3 +1,3 @@
 module CSS
-  VERSION = '0.1.5'
+  VERSION = '0.1.7'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p_css
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Keita Urashima
@@ -66,7 +66,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="