p_css 0.2.0.beta1-x86_64-linux

data/lib/css/cascade.rb

@@ -0,0 +1,277 @@
+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, `@media` chains are
+  # evaluated against the supplied context up-front, and rules are
+  # indexed by the rightmost compound's strongest anchor — id > class >
+  # tag > universal). `resolve(element)` then visits only the rules whose
+  # anchor could match the element.
+  #
+  # 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)
+      @index   = build_index(@entries)
+    end
+
+    # Returns Hash<String, Declaration> of winning declarations.
+    #
+    # `state:` opts into stateful-pseudo matching — see
+    # `Selectors::Matcher#matches?` for the shape. Defaults to the
+    # stateless behavior (`:hover`, `:focus`, etc. never match).
+    #
+    # `cache:` lets callers share a per-element context cache across many
+    # resolves. The default `{}` is local to one call. Pass a persistent
+    # Hash when the DOM is stable across many resolves — Context (tag, id,
+    # classes) computation runs once per element instead of per resolve.
+    # The caller is responsible for clearing/replacing the cache on DOM
+    # mutation.
+    def resolve(element, inline_style: nil, state: nil, cache: nil)
+      cache     ||= {}
+      candidates  = collect_candidate_indexes(element, cache)
+      order       = 0
+      matches     = []
+
+      candidates.each do |idx|
+        entry = @entries[idx]
+        spec  = best_matching_specificity(element, entry.selector_pairs, cache, state)
+
+        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
+
+    # Compile
+    # ----------------------------------------------------------------
+
+    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(_1, @context) }
+
+      sl    = Selectors::Parser.parse_selector_list(rule.prelude)
+      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
+      # 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
+
+    # Index
+    # ----------------------------------------------------------------
+
+    Index     = Data.define(:by_id, :by_class, :by_tag, :universal)
+    AnchorKey = Data.define(:kind, :name)
+
+    def build_index(entries)
+      by_id     = {}
+      by_class  = {}
+      by_tag    = {}
+      universal = []
+
+      entries.each_with_index do |entry, idx|
+        seen = Set.new
+
+        entry.selector_pairs.each do |sel, _spec|
+          key = anchor_key(sel)
+
+          next if seen.include?(key)
+
+          seen << key
+
+          case key.kind
+          when :id        then (by_id[key.name]    ||= []) << idx
+          when :class     then (by_class[key.name] ||= []) << idx
+          when :tag       then (by_tag[key.name]   ||= []) << idx
+          when :universal then universal                   << idx
+          end
+        end
+      end
+
+      Index.new(
+        by_id:     by_id.freeze,
+        by_class:  by_class.freeze,
+        by_tag:    by_tag.freeze,
+        universal: universal.freeze
+      )
+    end
+
+    # Picks the strongest anchor in the rightmost compound: id > class >
+    # tag > universal. Compounds whose only simple selectors are pseudos
+    # (e.g. `:hover`) or attribute matchers fall through to universal —
+    # they will be tested against every element, but real-world
+    # stylesheets rarely have many such rules.
+    def anchor_key(complex_selector)
+      class_name = nil
+      tag_name   = nil
+
+      complex_selector.compounds.last.components.each do |c|
+        case c
+        when Selectors::IdSelector    then return AnchorKey.new(kind: :id, name: c.name)
+        when Selectors::ClassSelector then class_name ||= c.name
+        when Selectors::TypeSelector  then tag_name   ||= c.name.downcase
+        end
+      end
+
+      return AnchorKey.new(kind: :class, name: class_name) if class_name
+      return AnchorKey.new(kind: :tag,   name: tag_name)   if tag_name
+
+      AnchorKey.new(kind: :universal, name: nil)
+    end
+
+    # Resolve helpers
+    # ----------------------------------------------------------------
+
+    # Buckets are appended in source-order at compile time, so each is
+    # already sorted ascending and unique. Concatenating them and using
+    # `sort! + uniq!` is cheaper than going through a `Set`: integers
+    # sort in C, and `uniq!` on a sorted array only removes adjacent
+    # duplicates.
+    def collect_candidate_indexes(element, cache)
+      out = []
+
+      el_id  = Selectors::Matcher.id_of(element, cache)
+      bucket = @index.by_id[el_id] if el_id
+
+      out.concat(bucket) if bucket
+
+      Selectors::Matcher.classes_of(element, cache).each do |cls|
+        bucket = @index.by_class[cls]
+        out.concat(bucket) if bucket
+      end
+
+      bucket = @index.by_tag[Selectors::Matcher.tag_of(element, cache)]
+      out.concat(bucket) if bucket
+
+      out.concat(@index.universal)
+      out.sort!
+      out.uniq!
+      out
+    end
+
+    def best_matching_specificity(element, selector_pairs, cache, state)
+      best = nil
+
+      selector_pairs.each do |sel, spec|
+        next unless Selectors::Matcher.matches?(element, sel, cache: cache, state: state)
+
+        best = spec if best.nil? || spec > best
+      end
+
+      best
+    end
+
+    # Single-pass running max per property name. Cheaper than group_by +
+    # max_by, and avoids allocating a fresh comparison key per
+    # declaration.
+    def pick_winners(matches)
+      best = {}
+
+      matches.each do |m|
+        name      = m.declaration.name
+        incumbent = best[name]
+
+        best[name] = m if incumbent.nil? || better?(m, incumbent)
+      end
+
+      best.transform_values(&:declaration)
+    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 { _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
+    end
+  end
+end

data/lib/css/code_points.rb

@@ -0,0 +1,59 @@
+module CSS
+  # Character class predicates from CSS Syntax §4.2 Definitions, plus the
+  # U+FFFD replacement character used both during tokenization and
+  # serialization.
+  #
+  # ASCII bytes are looked up in a precomputed boolean table (one Array
+  # access + one branch); non-ASCII code points (>= 0x80) are always
+  # ident-cp / ident-start per spec, so the helpers fall back to a single
+  # `c.ord >= 0x80` check. Avoids the chain of `String#<=>` calls a
+  # range-style predicate would dispatch.
+  module CodePoints
+    REPLACEMENT = "�".freeze
+
+    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[_1] = true }
+          else                   a[r] = true
+          end
+        }
+      }.freeze
+    end
+
+    DIGIT_TABLE       = build_table(0x30..0x39)
+    HEX_DIGIT_TABLE   = build_table(0x30..0x39, 0x41..0x46, 0x61..0x66)
+    IDENT_START_TABLE = build_table(0x41..0x5A, 0x61..0x7A, 0x5F)
+    IDENT_CP_TABLE    = build_table(0x30..0x39, 0x41..0x5A, 0x61..0x7A, 0x5F, 0x2D)
+
+    module_function
+
+    def digit?(c)
+      return false if c.nil?
+
+      o = c.ord
+      o < 128 && DIGIT_TABLE[o]
+    end
+
+    def hex_digit?(c)
+      return false if c.nil?
+
+      o = c.ord
+      o < 128 && HEX_DIGIT_TABLE[o]
+    end
+
+    def ident_start_code_point?(c)
+      return false if c.nil?
+
+      o = c.ord
+      o >= 128 || IDENT_START_TABLE[o]
+    end
+
+    def ident_code_point?(c)
+      return false if c.nil?
+
+      o = c.ord
+      o >= 128 || IDENT_CP_TABLE[o]
+    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

data/lib/css/media_queries/evaluator.rb

@@ -0,0 +1,157 @@
+module CSS
+  module MediaQueries
+    # Evaluates a MediaQueryList against a Context, returning true if at
+    # least one media-query in the list matches.
+    module Evaluator
+      extend self
+
+      # Length conversion to CSS px assumes 1em = 1rem = 16px. Per Media
+      # Queries Level 4 §1.3 this is the conventional fallback when the
+      # font-size of the root is unknown.
+      EM_PX = 16.0
+
+      LENGTH_UNITS_PX = {
+        'px'  => 1.0,
+        'em'  => EM_PX,
+        'rem' => EM_PX,
+        'ex'  => EM_PX * 0.5,
+        'ch'  => EM_PX * 0.5,
+        'pt'  => 96.0 / 72,
+        'pc'  => 16.0,
+        'in'  => 96.0,
+        'cm'  => 96.0 / 2.54,
+        'mm'  => 96.0 / 25.4,
+        'q'   => 96.0 / 25.4 / 4
+      }.freeze
+
+      RESOLUTION_UNITS_DPPX = {
+        'dppx' => 1.0,
+        'x'    => 1.0,
+        'dpi'  => 1.0 / 96,
+        'dpcm' => 2.54 / 96
+      }.freeze
+
+      RESOLUTION_FEATURES = %w[resolution].freeze
+
+      INVERSE_OP = {lt: :gt, le: :ge, gt: :lt, ge: :le, eq: :eq}.freeze
+
+      PREFIX_OP = {min: :ge, max: :le}.freeze
+
+      def evaluate(query_list, context)
+        query_list.queries.any? { evaluate_query(_1, context) }
+      end
+
+      private
+
+      def evaluate_query(query, context)
+        result = evaluate_query_main(query, context)
+        query.modifier == :not ? !result : result
+      end
+
+      def evaluate_query_main(query, context)
+        if query.type
+          return false unless type_matches?(query.type, context.media_type)
+        end
+
+        return true if query.condition.nil?
+
+        evaluate_condition(query.condition, context)
+      end
+
+      def type_matches?(type, ctx_type)
+        type == 'all' || type == ctx_type.to_s
+      end
+
+      def evaluate_condition(node, context)
+        case node
+        when MediaNot       then !evaluate_condition(node.operand, 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
+        end
+      end
+
+      def evaluate_feature(feature, context)
+        ctx_name, prefix = strip_prefix(feature.name)
+        ctx_value = context[ctx_name]
+
+        return evaluate_boolean(ctx_value) if feature.op.nil?
+
+        compare(prefix, feature.op, ctx_value, feature.value, ctx_name)
+      end
+
+      def evaluate_boolean(ctx_value)
+        return false if ctx_value.nil?
+        return false if ctx_value == 0 || ctx_value == false || ctx_value == '' || ctx_value == 'none'
+
+        true
+      end
+
+      def strip_prefix(name)
+        case name
+        when /\Amin-(.+)/ then [$1, :min]
+        when /\Amax-(.+)/ then [$1, :max]
+        else                   [name, nil]
+        end
+      end
+
+      def compare(prefix, op, ctx_value, feature_value, ctx_name)
+        op = PREFIX_OP[prefix] || op
+
+        return string_op_apply(op, ctx_value.to_s, feature_value.value.to_s) if ident_compare?(feature_value)
+
+        a = numeric_for(ctx_name, ctx_value)
+        b = numeric_for(ctx_name, feature_value)
+
+        return false if a.nil? || b.nil?
+
+        numeric_op_apply(op, a, b)
+      end
+
+      def ident_compare?(feature_value)
+        feature_value.is_a?(Token) && feature_value.type == :ident
+      end
+
+      def string_op_apply(op, a, b)
+        op == :eq && a.casecmp?(b)
+      end
+
+      def numeric_op_apply(op, a, b)
+        case op
+        when :eq then a == b
+        when :lt then a < b
+        when :le then a <= b
+        when :gt then a > b
+        when :ge then a >= b
+        end
+      end
+
+      # Converts both context value and feature value to a comparable
+      # numeric in the canonical unit for the named feature.
+      def numeric_for(ctx_name, value)
+        case value
+        when Numeric then value.to_f
+        when Ratio   then value.to_f
+        when Token
+          case value.type
+          when :number     then value.value.to_f
+          when :percentage then value.value.to_f / 100
+          when :dimension  then dimension_to_canonical(value, ctx_name)
+          else                  nil
+          end
+        else nil
+        end
+      end
+
+      def dimension_to_canonical(token, ctx_name)
+        unit  = token.unit.downcase
+        table = RESOLUTION_FEATURES.include?(ctx_name) ? RESOLUTION_UNITS_DPPX : LENGTH_UNITS_PX
+
+        factor = table[unit]
+        factor && token.value.to_f * factor
+      end
+    end
+  end
+end

data/lib/css/media_queries/nodes.rb

@@ -0,0 +1,41 @@
+module CSS
+  module MediaQueries
+    # Marker module for media-query AST nodes; lets the main serializer
+    # dispatch into MediaQueries::Serializer when it ever exists.
+    module Node; end
+
+    MediaQueryList = Data.define(:queries) do
+      include Node
+    end
+
+    # `modifier` is `nil`, `:not`, or `:only`.
+    # `type` is `nil` or a downcased string ('screen', 'print', 'all', ...).
+    # `condition` is `nil` or a media-condition node.
+    MediaQuery = Data.define(:modifier, :type, :condition) do
+      include Node
+    end
+
+    MediaNot = Data.define(:operand)        { include Node }
+    MediaAnd = Data.define(:operands)       { include Node }
+    MediaOr  = Data.define(:operands)       { include Node }
+
+    # `op` is `nil` (boolean form, e.g. `(color)`), `:eq` (plain form,
+    # `(min-width: 600px)`, or range `=`), `:lt`, `:le`, `:gt`, or `:ge`.
+    # `value` is `nil` (boolean), a Token, or a Ratio.
+    MediaFeature = Data.define(:name, :op, :value) do
+      include Node
+    end
+
+    # Catch-all for `(...)` content the parser couldn't recognize as a
+    # feature or condition. Preserved so downstream tools can still see it.
+    GeneralEnclosed = Data.define(:tokens) do
+      include Node
+    end
+
+    # Numeric ratio used in `aspect-ratio` / `device-aspect-ratio` features.
+    Ratio = Data.define(:numerator, :denominator) do
+      include Node
+      def to_f = numerator.to_f / denominator
+    end
+  end
+end