p_css 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc053cb635310340632520bdf6ef0771e1003b5d2f8582434078667cc9aeb7b4
+  data.tar.gz: b5e3c26f959dfb92e86126aab069b293796e762fb5388baef6be7c98b7b7499e
+SHA512:
+  metadata.gz: 6803cd828b9d6b2ffeaf7c3c82e75345e7b1165dff0e93e4390ebf9eb4ea7a74bcd45453582562f44bcdb45cc614389c41e60bfc94ba2865421c1cc2ea9399b6
+  data.tar.gz: e6acedb22e9a43e81014dfff4d65378d88eda70f515936fd9f0962778e2c3aa4786cf608c8713fc0d3985e10dfb6919d77fcfe61cdd85b1263603b290fcbadb2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keita Urashima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,302 @@
+# p CSS
+
+A CSS toolkit for Ruby — tokenizer, parser, serializer, selector matcher, and
+cascade resolver. Targets CSS Syntax Level 4 (with nesting), Selectors Level 4,
+and Media Queries Level 4.
+
+The name reads as **p CSS** — Ruby's `p` method (puts-inspect) applied to CSS.
+Installed under the gem name `p_css`; the top-level module is `CSS`.
+
+```ruby
+require 'p_css'
+
+CSS.parse_stylesheet('.foo { color: red }')
+```
+
+## Why this exists
+
+The Ruby ecosystem already has a few CSS parsers (crass, sass-rb's grammar,
+nokogiri's selector-to-XPath compiler), but each stops at a different layer
+and none of them currently:
+
+- parse modern CSS nesting (`& .child { ... }`),
+- expose a Selectors Level 4 AST you can inspect,
+- match selectors against a DOM in pure Ruby,
+- resolve the cascade so `display: none` in a `<style>` tag actually
+  influences a visibility judgement.
+
+p CSS fills that gap. The first concrete user is
+[capybara-simulated](https://github.com/ursm/capybara-simulated) (a
+Nokogiri + QuickJS Capybara driver that needs to know whether an element
+is hidden without a real browser), but the gem is intentionally general —
+no DOM library is hardwired in.
+
+## What's in the box
+
+| Layer | Entry point | Spec |
+| --- | --- | --- |
+| Tokenizer | `CSS.tokenize` | Syntax 4 §4 |
+| Parser (with nesting) | `CSS.parse_stylesheet` and §5.3 entry points | Syntax 4 §5, Nesting 1 |
+| Serializer (round-trip) | `CSS.serialize` | Syntax 4 §9 |
+| `urange` | `CSS.parse_urange` | Syntax 4 §6 |
+| Selector parser | `CSS.parse_selector_list`, `CSS.parse_selector` | Selectors 4 |
+| AnB microsyntax | `CSS.parse_anb` | Syntax 4 §6.7 |
+| Specificity | `CSS.specificity` | Selectors §16 |
+| Selector matcher | `CSS.matches?` | 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 |
+| Cascade resolver | `CSS.cascade(...).resolve(element)` | Cascade & Inheritance 4 (subset) |
+
+## Install
+
+```ruby
+# Gemfile
+gem 'p_css'
+```
+
+Or:
+
+```sh
+bundle add p_css
+```
+
+Ruby 3.4+ 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.
+
+## Quick tour
+
+### Parse a stylesheet
+
+```ruby
+ss = CSS.parse_stylesheet(<<~CSS)
+  .card, .panel {
+    color: red;
+    & .title { font-weight: 700; }
+    @media (min-width: 600px) { padding: 2rem; }
+  }
+CSS
+
+ss.rules.size                     # => 1
+ss.rules.first.block.items.count  # => 3 (1 declaration + 1 nested rule + 1 nested at-rule)
+```
+
+`CSS.parse` is an alias of `CSS.parse_stylesheet`.
+
+### Round-trip
+
+`CSS.serialize` accepts any AST node, Token, or array of component values, and
+emits CSS that re-parses to the same AST.
+
+```ruby
+src = '.foo { color: #abc; & .x { font-weight: 700 !important; } }'
+CSS.serialize(CSS.parse_stylesheet(src))
+# => ".foo {\n  color: #abc;\n  & .x {\n    font-weight: 700 !important;\n  }\n}"
+```
+
+### Spec entry points
+
+```ruby
+CSS.parse_rule('@charset "UTF-8";')                  # one rule
+CSS.parse_declaration('color: red !important')       # one declaration
+CSS.parse_block_contents('color: red; padding: 1em') # for `style="..."` etc.
+CSS.parse_component_value('rgb(1, 2, 3)')            # one component value
+CSS.parse_component_values('1px solid red')          # array of component values
+CSS.parse_comma_separated_values('1px, 2px, 3px')    # array of arrays
+```
+
+### Comments and source positions
+
+```ruby
+ts = CSS.tokenize("a /* hi */ b\n c", preserve_comments: true)
+ts.map { [it.type, it.value, it.position.to_s] }
+# => [[:ident, "a", "1:1"],
+#     [:whitespace, nil, "1:2"],
+#     [:comment, " hi ", "1:3"],
+#     ...]
+```
+
+`Token#position` is set during tokenization (`line`, `column`, `offset`,
+`end_offset`). Equality on `Token` ignores position, so hand-built tokens still
+compare equal to parsed ones.
+
+`ParseError#position` carries the same information, and the message is prefixed
+`line:col:` when available.
+
+### Selectors
+
+```ruby
+sl = CSS.parse_selector_list('.card > a:hover, [data-x="y" i]:nth-child(2n+1)')
+sl.selectors.size                   # => 2
+sl.selectors[0].combinators         # => [:child]
+
+compound = sl.selectors[1].compounds[0]
+attr = compound.components[0]
+attr.matcher                        # => :exact
+attr.case_flag                      # => :i
+
+nth = compound.components[1]
+nth.argument                        # => CSS::Selectors::AnB(step: 2, offset: 1)
+```
+
+The selector parser also accepts the prelude of a parsed rule directly (the
+prelude can contain `Function` / `SimpleBlock` nodes from the main parser; they
+are flattened back into a token stream automatically):
+
+```ruby
+ss = CSS.parse_stylesheet('.x { ... }')
+CSS.parse_selector_list(ss.rules.first.prelude)
+```
+
+### Specificity
+
+```ruby
+CSS.specificity(CSS.parse_selector_list('div.a#b')) # => Specificity(1, 1, 1)
+CSS.specificity(CSS.parse_selector_list(':where(#x)')) # => Specificity(0, 0, 0)
+CSS.specificity(CSS.parse_selector_list(':is(.a, #b)')) # => Specificity(1, 0, 0)
+```
+
+`Specificity` is `Comparable`, so `>`, `<`, `==` work as expected.
+
+### Matcher
+
+`CSS.matches?(element, selector)` checks whether a duck-typed element matches a
+selector. The element must respond to `name` (or `tag_name`), `[]`, `parent`,
+sibling navigation (`previous_element` / `next_element` if defined; otherwise
+`previous_sibling` / `next_sibling`), and `children`. Nokogiri elements satisfy
+this without any wrapping.
+
+```ruby
+require 'nokogiri'
+
+doc = Nokogiri::HTML(<<~HTML)
+  <ul>
+    <li>one</li>
+    <li class="active">two</li>
+    <li>three</li>
+  </ul>
+HTML
+
+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
+```
+
+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
+component values).
+
+### Nesting de-sugar
+
+`CSS.desugar` returns a flat Stylesheet with `&` substituted by the parent
+selector. Single-compound parents inline directly; multi-selector parents
+collapse to `:is(...)`.
+
+```ruby
+src = <<~CSS
+  .card, .panel {
+    color: red;
+    & .title { font-weight: 700; }
+  }
+CSS
+
+CSS.serialize(CSS.desugar(CSS.parse_stylesheet(src)))
+# .card, .panel {
+#   color: red;
+# }
+# :is(.card, .panel) .title {
+#   font-weight: 700;
+# }
+```
+
+### Media queries
+
+```ruby
+ql = CSS.parse_media_query_list('screen and (600px <= width < 1200px)')
+
+ctx = CSS::MediaQueries::Context.default('width' => 800)
+CSS.media_matches?(ql, ctx)         # => true
+
+ctx = CSS::MediaQueries::Context.default('width' => 1500)
+CSS.media_matches?(ql, ctx)         # => false
+```
+
+`Context` is a feature-name-keyed Hash with sensible defaults (1024×768
+landscape light-mode screen). Override per call:
+
+```ruby
+ctx = CSS::MediaQueries::Context.default(
+  'width' => 1200,
+  'prefers-color-scheme' => 'dark'
+)
+```
+
+Length units (px, em, rem, pt, pc, in, cm, mm, Q) are converted to CSS px
+against a 16-px root assumption; resolution units (dppx, x, dpi, dpcm) to
+dppx.
+
+### Cascade
+
+`Cascade` resolves the winning declaration per property for one element.
+Construct once per stylesheet (selectors, media queries, and specificities are
+pre-computed); call `resolve(element)` cheaply per element.
+
+```ruby
+ss = CSS.parse_stylesheet(<<~CSS)
+  p { color: black; }
+  .lead { color: blue; }
+  p.special { color: red !important; }
+  @media (max-width: 600px) {
+    .lead { font-size: 0.875rem; }
+  }
+CSS
+
+ctx     = CSS::MediaQueries::Context.default('width' => 1024)
+cascade = CSS.cascade(ss, context: ctx)
+
+el = Nokogiri::HTML('<p class="lead special">…</p>').at_css('p')
+winners = cascade.resolve(el, inline_style: el['style'])
+
+CSS.serialize(winners['color'].value)   # => "red"
+winners['color'].important              # => true
+winners['font-size']                    # => nil  (only fires for max-width: 600px)
+```
+
+The cascade sort follows: `!important` > inline > stylesheet > specificity >
+source order. Cascade layers, `@scope` proximity, and Shadow DOM
+encapsulation are not modeled — `@layer` / `@supports` / `@scope` /
+`@container` / `@starting-style` blocks are descended into unconditionally.
+
+### `urange`
+
+```ruby
+r = CSS.parse_urange('U+10??')
+r.first      # => 0x1000
+r.last       # => 0x10FF
+r.cover?(0x10AB)  # => true
+r.to_s       # => "U+1000-10FF"
+```
+
+## Out of scope
+
+These are deliberate omissions; pull requests welcome:
+
+- Selectors Level 4 namespace prefixes (`ns|*`)
+- 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`
+  clipping). p CSS reports the resolved property values; deciding whether
+  those values produce a zero-sized box is outside its scope.
+
+## Compatibility
+
+Ruby 3.4+. Tested on the current MRI. No mandatory runtime dependencies.
+
+## License
+
+MIT.

data/lib/css/cascade.rb

@@ -0,0 +1,168 @@
+module CSS
+  # Resolves the cascade for a Stylesheet against a single element. Returns
+  # `Hash<String, Declaration>` keyed by property name with the winning
+  # declaration after applying:
+  #
+  #   - `@media` filtering (against a `MediaQueries::Context`)
+  #   - selector matching (`Selectors::Matcher`)
+  #   - cascade sort: `!important` > origin / inline > specificity > source order
+  #
+  # The Stylesheet is compiled once on construction (selectors are
+  # pre-parsed, specificities pre-computed, and `@media` chains are
+  # evaluated against the supplied context up-front so non-matching rules
+  # are dropped). `resolve(element)` is then cheap to call per node.
+  #
+  # Cascade layers, `@scope` proximity, and Shadow DOM encapsulation are
+  # not modeled — `@layer`, `@supports`, `@container`, `@scope`, and
+  # `@starting-style` blocks are descended into unconditionally.
+  class Cascade
+    Match = Data.define(:declaration, :specificity, :inline, :order)
+
+    RuleEntry = Data.define(:selector_pairs, :declarations)
+
+    TRANSPARENT_AT_RULES = %w[supports layer scope starting-style container].freeze
+
+    def initialize(stylesheet, context: MediaQueries::Context.default)
+      @context = context
+      @entries = compile(stylesheet)
+    end
+
+    # Returns Hash<String, Declaration> of winning declarations.
+    def resolve(element, inline_style: nil)
+      order   = 0
+      matches = []
+
+      @entries.each do |entry|
+        spec = best_matching_specificity(element, entry.selector_pairs)
+        next if spec.nil?
+
+        entry.declarations.each do |decl|
+          order += 1
+          matches << Match.new(declaration: decl, specificity: spec, inline: false, order: order)
+        end
+      end
+
+      if inline_style
+        inline_declarations(inline_style).each do |decl|
+          order += 1
+          matches << Match.new(declaration: decl, specificity: Selectors::Specificity::ZERO, inline: true, order: order)
+        end
+      end
+
+      pick_winners(matches)
+    end
+
+    private
+
+    def compile(stylesheet)
+      out = []
+      walk(stylesheet.rules, [], out)
+      out
+    end
+
+    # Filters the stylesheet down to rules whose `@media` chain (if any)
+    # matches the cascade's context, pre-parsing every selector list and
+    # caching its specificity per selector.
+    def walk(rules, media_chain, out)
+      rules.each do |rule|
+        case rule
+        when Nodes::QualifiedRule
+          register_qualified_rule(rule, media_chain, out)
+        when Nodes::AtRule
+          dispatch_at_rule(rule, media_chain, out)
+        end
+      end
+    end
+
+    def register_qualified_rule(rule, media_chain, out)
+      return unless media_chain.all? { MediaQueries::Evaluator.evaluate(it, @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) }
+
+      out << RuleEntry.new(selector_pairs: pairs, declarations: decls)
+    rescue ParseError
+      # Browsers drop a rule whose prelude doesn't parse as a selector
+      # list rather than poisoning the whole stylesheet; do the same.
+    end
+
+    def dispatch_at_rule(rule, media_chain, out)
+      return unless rule.block
+
+      case rule.name.downcase
+      when 'media'
+        ql = MediaQueries::Parser.parse(rule.prelude)
+        walk(rule.block.items, [*media_chain, ql], out)
+      when *TRANSPARENT_AT_RULES
+        walk(rule.block.items, media_chain, out)
+      end
+    rescue ParseError
+      # Bad media prelude → skip this @media block; rules outside it
+      # remain unaffected.
+    end
+
+    def best_matching_specificity(element, selector_pairs)
+      best = nil
+
+      selector_pairs.each do |sel, spec|
+        next unless Selectors::Matcher.matches?(element, sel)
+
+        best = spec if best.nil? || spec > best
+      end
+
+      best
+    end
+
+    # Single-pass: keep the running winner per property name. Cheaper than
+    # group_by + max_by, and more importantly avoids allocating a fresh
+    # comparison key per declaration.
+    def pick_winners(matches)
+      winners       = {}
+      winner_matches = {}
+
+      matches.each do |m|
+        name      = m.declaration.name
+        incumbent = winner_matches[name]
+
+        if incumbent.nil? || better?(m, incumbent)
+          winners[name]        = m.declaration
+          winner_matches[name] = m
+        end
+      end
+
+      winners
+    end
+
+    # `m` outranks `incumbent` when its priority class is higher, or — at
+    # the same priority class — its specificity is greater, or — at equal
+    # specificity — it appeared later in source order.
+    def better?(m, incumbent)
+      a = priority(m)
+      b = priority(incumbent)
+      return a > b unless a == b
+
+      cmp = m.specificity <=> incumbent.specificity
+      return cmp.positive? unless cmp.zero?
+
+      m.order > incumbent.order
+    end
+
+    # !important and inline style each bump the rule into a higher
+    # priority class. Encoded so that `priority(a) <=> priority(b)`
+    # captures the cascade's origin/importance ordering.
+    def priority(m)
+      (m.declaration.important ? 2 : 0) + (m.inline ? 1 : 0)
+    end
+
+    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) }
+      else
+        raise ArgumentError, "cannot derive inline declarations from #{style.class}"
+      end
+    end
+  end
+end

data/lib/css/code_points.rb

@@ -0,0 +1,36 @@
+module CSS
+  # Character class predicates from CSS Syntax §4.2 Definitions, plus the
+  # U+FFFD replacement character used both during tokenization and
+  # serialization. Implemented with char comparisons rather than regex to
+  # avoid pattern-match overhead in the tokenizer's inner loop.
+  module CodePoints
+    REPLACEMENT = "�".freeze
+
+    module_function
+
+    def digit?(c)
+      !c.nil? && c >= '0' && c <= '9'
+    end
+
+    def hex_digit?(c)
+      return false if c.nil?
+
+      (c >= '0' && c <= '9') || (c >= 'A' && c <= 'F') || (c >= 'a' && c <= 'f')
+    end
+
+    def ident_start_code_point?(c)
+      return false if c.nil?
+      return true  if c == '_' || (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
+
+      c.ord >= 0x80
+    end
+
+    def ident_code_point?(c)
+      return false if c.nil?
+      return true  if c == '_' || c == '-' || (c >= '0' && c <= '9')
+      return true  if (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
+
+      c.ord >= 0x80
+    end
+  end
+end

data/lib/css/escape.rb

@@ -0,0 +1,82 @@
+module CSS
+  # CSS Syntax §9.3 escape primitives — `serialize an identifier`,
+  # `serialize a name`, and `serialize a string`. Reused by both the main
+  # serializer and the selector serializer.
+  module Escape
+    extend self
+    extend CodePoints
+
+    # §9.3.1.
+    def ident(ident)
+      buf       = +''
+      lone_dash = ident.length == 1 && ident == '-'
+      hyphen0   = ident.start_with?('-')
+
+      ident.each_char.with_index {|c, i|
+        cp = c.ord
+
+        if (esc = control_or_nul(cp))
+          buf << esc
+        elsif i.zero? && lone_dash
+          buf << '\\-'
+        elsif (i.zero? && digit?(c)) || (i == 1 && hyphen0 && digit?(c))
+          buf << format('\\%x ', cp)
+        elsif ident_code_point?(c)
+          buf << c
+        else
+          buf << "\\#{c}"
+        end
+      }
+
+      buf
+    end
+
+    # §9.3 "Serialize a name". Like an ident but allows leading digits
+    # and hyphens — used for unrestricted hash tokens.
+    def name(name)
+      buf = +''
+
+      name.each_char {|c|
+        cp = c.ord
+
+        if (esc = control_or_nul(cp))
+          buf << esc
+        elsif ident_code_point?(c)
+          buf << c
+        else
+          buf << "\\#{c}"
+        end
+      }
+
+      buf
+    end
+
+    # §9.3.2. Always uses double quotes.
+    def string(s)
+      buf = +'"'
+
+      s.each_char {|c|
+        cp = c.ord
+
+        if (esc = control_or_nul(cp))
+          buf << esc
+        elsif c == '"' || c == '\\'
+          buf << "\\#{c}"
+        else
+          buf << c
+        end
+      }
+
+      buf << '"'
+    end
+
+    # NUL collapses to U+FFFD; controls (0x01..0x1F, 0x7F) get hex
+    # escapes. Returns nil for non-control code points.
+    def control_or_nul(cp)
+      return CodePoints::REPLACEMENT if cp.zero?
+      return format('\\%x ', cp)     if (0x01..0x1F).cover?(cp) || cp == 0x7F
+
+      nil
+    end
+  end
+end

data/lib/css/media_queries/context.rb

@@ -0,0 +1,60 @@
+module CSS
+  module MediaQueries
+    # Holds the user-agent context against which a MediaQueryList is
+    # evaluated. Stored as a feature → value Hash; values follow Media
+    # Queries Level 4 conventions:
+    #
+    #   - lengths in CSS pixels (Numeric)
+    #   - resolution in dots-per-CSS-px (`dppx`, Numeric)
+    #   - identifier-valued features as Strings ("landscape", "dark", ...)
+    #   - boolean-style features as 1 / 0 or true / false
+    #
+    # `Context.default(**overrides)` returns a sensible desktop preset.
+    Context = Data.define(:features) do
+      def [](name) = features[name.to_s]
+
+      def media_type = self['media-type']
+
+      def with(**overrides)
+        Context.new(features: features.merge(overrides.transform_keys(&:to_s)))
+      end
+
+      def self.default(**overrides)
+        new(features: DEFAULTS.merge(overrides.transform_keys(&:to_s)))
+      end
+
+      DEFAULTS = {
+        'media-type'          => 'screen',
+
+        'width'               => 1024,
+        'height'              => 768,
+        'device-width'        => 1024,
+        'device-height'       => 768,
+        'aspect-ratio'        => 1024.0 / 768,
+        'device-aspect-ratio' => 1024.0 / 768,
+        'orientation'         => 'landscape',
+
+        'resolution'          => 1, # dppx
+        'color'               => 8,
+        'color-gamut'         => 'srgb',
+        'color-index'         => 0,
+        'monochrome'          => 0,
+        'grid'                => 0,
+        'scan'                => 'progressive',
+        'update'              => 'fast',
+        'overflow-block'      => 'scroll',
+        'overflow-inline'     => 'scroll',
+
+        'pointer'             => 'fine',
+        'hover'               => 'hover',
+        'any-pointer'         => 'fine',
+        'any-hover'           => 'hover',
+
+        'prefers-color-scheme'   => 'light',
+        'prefers-reduced-motion' => 'no-preference',
+        'prefers-contrast'       => 'no-preference',
+        'forced-colors'          => 'none'
+      }.freeze
+    end
+  end
+end