p_css 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc053cb635310340632520bdf6ef0771e1003b5d2f8582434078667cc9aeb7b4
-  data.tar.gz: b5e3c26f959dfb92e86126aab069b293796e762fb5388baef6be7c98b7b7499e
+  metadata.gz: 772060eec5d726253913cd8be2daa6180429680d014c1752c9b26b15618e4ba8
+  data.tar.gz: edd5e5afc5871362dc21cca89d8eb6a5b085350022f79f2b8c6f07a032f07aaa
 SHA512:
-  metadata.gz: 6803cd828b9d6b2ffeaf7c3c82e75345e7b1165dff0e93e4390ebf9eb4ea7a74bcd45453582562f44bcdb45cc614389c41e60bfc94ba2865421c1cc2ea9399b6
-  data.tar.gz: e6acedb22e9a43e81014dfff4d65378d88eda70f515936fd9f0962778e2c3aa4786cf608c8713fc0d3985e10dfb6919d77fcfe61cdd85b1263603b290fcbadb2
+  metadata.gz: 7b7e331023830f09938bbd03a29f50c49b19b40169226a9c13866c1ce2436b0dcd71987fb183f403b7b98784c68c8e8426e6043dd3757ebe5343e37862e2c228
+  data.tar.gz: c06594e2e861c77e56cc32dcb1980b3fba8bfe0175fa1f108e4b0d02bef929efd59274e5c53f04ecea8245b47c583f41eb8a4396a5689052a569af54e8026f5a

data/lib/css/cascade.rb

@@ -8,9 +8,11 @@ module CSS
   #   - 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.
+  # 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
@@ -25,15 +27,20 @@ module CSS
     def initialize(stylesheet, context: MediaQueries::Context.default)
       @context = context
       @entries = compile(stylesheet)
+      @index   = build_index(@entries)
     end
 
     # Returns Hash<String, Declaration> of winning declarations.
     def resolve(element, inline_style: nil)
-      order   = 0
-      matches = []
+      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)
 
-      @entries.each do |entry|
-        spec = best_matching_specificity(element, entry.selector_pairs)
         next if spec.nil?
 
         entry.declarations.each do |decl|
@@ -54,6 +61,9 @@ module CSS
 
     private
 
+    # Compile
+    # ----------------------------------------------------------------
+
     def compile(stylesheet)
       out = []
       walk(stylesheet.rules, [], out)
@@ -77,7 +87,7 @@ module CSS
     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)
+      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) }
 
@@ -102,11 +112,103 @@ module CSS
       # remain unaffected.
     end
 
-    def best_matching_specificity(element, selector_pairs)
+    # 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)
       best = nil
 
       selector_pairs.each do |sel, spec|
-        next unless Selectors::Matcher.matches?(element, sel)
+        next unless Selectors::Matcher.matches?(element, sel, cache: cache)
 
         best = spec if best.nil? || spec > best
       end
@@ -114,24 +216,20 @@ module CSS
       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.
+    # 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)
-      winners       = {}
-      winner_matches = {}
+      best = {}
 
       matches.each do |m|
         name      = m.declaration.name
-        incumbent = winner_matches[name]
+        incumbent = best[name]
 
-        if incumbent.nil? || better?(m, incumbent)
-          winners[name]        = m.declaration
-          winner_matches[name] = m
-        end
+        best[name] = m if incumbent.nil? || better?(m, incumbent)
       end
 
-      winners
+      best.transform_values(&:declaration)
     end
 
     # `m` outranks `incumbent` when its priority class is higher, or — at

data/lib/css/selectors/matcher.rb

@@ -26,16 +26,24 @@ module CSS
       LINK_TAGS        = %w[a area link].freeze
       RO_INPUT_TYPES   = %w[hidden range color checkbox radio file submit image reset button].freeze
 
-      def matches?(element, selector)
+      # Per-element cache used to avoid recomputing tag / id / class set
+      # for every selector in a hot loop (e.g. `Cascade#resolve` against
+      # hundreds of rules). Keyed by `Object#object_id`; only valid for
+      # the duration of a single matcher invocation.
+      Context = Data.define(:tag, :id, :classes)
+
+      EMPTY_CLASS_SET = Set.new.freeze
+
+      def matches?(element, selector, cache: nil)
         sel = selector.is_a?(String) ? Parser.parse_selector_list(selector) : selector
 
         case sel
         when SelectorList
-          sel.selectors.any? { match_complex(element, it) }
+          sel.selectors.any? { match_complex(element, it, cache) }
         when ComplexSelector
-          match_complex(element, sel)
+          match_complex(element, sel, cache)
         when CompoundSelector
-          match_compound(element, sel)
+          match_compound(element, sel, cache)
         else
           raise ArgumentError, "expected a selector node or string, got #{sel.class}"
         end
@@ -46,32 +54,32 @@ module CSS
       # 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.
-      def match_complex(element, complex)
-        match_at(element, complex, complex.compounds.size - 1)
+      def match_complex(element, complex, cache)
+        match_at(element, complex, complex.compounds.size - 1, cache)
       end
 
-      def match_at(element, complex, index)
+      def match_at(element, complex, index, cache)
         return false if element.nil?
-        return false unless match_compound(element, complex.compounds[index])
+        return false unless match_compound(element, complex.compounds[index], cache)
         return true  if index.zero?
 
         prev = index - 1
 
         case complex.combinators[prev]
-        when :descendant         then walk_until_match(element, complex, prev, :parent_element)
-        when :child              then match_at(parent_element(element), complex, prev)
-        when :next_sibling       then match_at(previous_element(element), complex, prev)
-        when :subsequent_sibling then walk_until_match(element, complex, prev, :previous_element)
+        when :descendant         then walk_until_match(element, complex, prev, :parent_element, cache)
+        when :child              then match_at(parent_element(element), complex, prev, cache)
+        when :next_sibling       then match_at(previous_element(element), complex, prev, cache)
+        when :subsequent_sibling then walk_until_match(element, complex, prev, :previous_element, cache)
         end
       end
 
       # Steps along the DOM via `direction` until a candidate matches the
       # remaining complex selector or the chain runs out.
-      def walk_until_match(element, complex, index, direction)
+      def walk_until_match(element, complex, index, direction, cache)
         candidate = send(direction, element)
 
         while candidate
-          return true if match_at(candidate, complex, index)
+          return true if match_at(candidate, complex, index, cache)
 
           candidate = send(direction, candidate)
         end
@@ -79,24 +87,63 @@ module CSS
         false
       end
 
-      def match_compound(element, compound)
-        compound.components.all? { match_simple(element, it) }
+      def match_compound(element, compound, cache)
+        compound.components.all? { match_simple(element, it, cache) }
       end
 
-      def match_simple(element, simple)
+      def match_simple(element, simple, cache)
         case simple
-        when TypeSelector      then tag(element).casecmp?(simple.name)
+        when TypeSelector      then tag_of(element, cache).casecmp?(simple.name)
         when UniversalSelector then true
-        when IdSelector        then attr(element, 'id') == simple.name
-        when ClassSelector     then class_list(element).include?(simple.name)
+        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)
-        when PseudoClass       then match_pseudo_class(element, simple)
+        when PseudoClass       then match_pseudo_class(element, simple, cache)
         when PseudoElement     then false
         when NestingSelector   then false
         else                        false
         end
       end
 
+      # Public — used by `Cascade` for both rule indexing and matching;
+      # callers can share a `cache` Hash with `matches?(cache: cache)`
+      # so each element pays for its tag / id / class set at most once.
+      public
+
+      def tag_of(element, cache = nil)
+        ctx = context_for(element, cache)
+        ctx ? ctx.tag : tag(element)
+      end
+
+      def id_of(element, cache = nil)
+        ctx = context_for(element, cache)
+        ctx ? ctx.id : attr(element, 'id')
+      end
+
+      def classes_of(element, cache = nil)
+        ctx = context_for(element, cache)
+        ctx ? ctx.classes : build_class_set(element)
+      end
+
+      private
+
+      def context_for(element, cache)
+        return nil if cache.nil?
+
+        cache[element.object_id] ||= Context.new(
+          tag:     tag(element),
+          id:      attr(element, 'id'),
+          classes: build_class_set(element)
+        )
+      end
+
+      def build_class_set(element)
+        v = attr(element, 'class')
+        return EMPTY_CLASS_SET if v.nil? || v.empty?
+
+        v.to_s.split(/\s+/).to_set
+      end
+
       # Attribute matching ----------------------------------------------
 
       def match_attribute(element, attr_sel)
@@ -125,10 +172,10 @@ module CSS
 
       # Pseudo-class matching -------------------------------------------
 
-      def match_pseudo_class(element, pc)
+      def match_pseudo_class(element, pc, cache)
         case pc.name.downcase
-        when 'is', 'where', 'matches'   then match_selector_list_arg(element, pc.argument)
-        when 'not'                       then negate_selector_list_arg(element, pc.argument)
+        when 'is', 'where', 'matches'   then match_selector_list_arg(element, pc.argument, cache)
+        when 'not'                       then negate_selector_list_arg(element, pc.argument, cache)
         when 'has'                       then false
         when 'root'                      then parent_element(element).nil?
         when 'scope'                     then parent_element(element).nil?
@@ -159,12 +206,12 @@ module CSS
         end
       end
 
-      def match_selector_list_arg(element, arg)
-        arg.is_a?(SelectorList) && matches?(element, arg)
+      def match_selector_list_arg(element, arg, cache)
+        arg.is_a?(SelectorList) && matches?(element, arg, cache: cache)
       end
 
-      def negate_selector_list_arg(element, arg)
-        arg.is_a?(SelectorList) && !matches?(element, arg)
+      def negate_selector_list_arg(element, arg, cache)
+        arg.is_a?(SelectorList) && !matches?(element, arg, cache: cache)
       end
 
       def match_nth(element, anb, of_type:, from_end:)
@@ -378,10 +425,6 @@ module CSS
         element[lower]
       end
 
-      def class_list(element)
-        attr(element, 'class').to_s.split(/\s+/)
-      end
-
       def parent_element(element)
         p = element.respond_to?(:parent) ? element.parent : nil
 

data/lib/css/version.rb

@@ -1,3 +1,3 @@
 module CSS
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/sig/css/cascade.rbs

@@ -0,0 +1,22 @@
+module CSS
+  # See `CSS.cascade` for the typical entry point.
+  class Cascade
+    type inline_style = String | Nodes::Block | Array[Nodes::Declaration]
+
+    class Match < Data
+      attr_reader declaration: Nodes::Declaration
+      attr_reader specificity: Selectors::Specificity
+      attr_reader inline: bool
+      attr_reader order: Integer
+
+      def self.new: (declaration: Nodes::Declaration, specificity: Selectors::Specificity, inline: bool, order: Integer) -> Match
+    end
+
+    def initialize: (Nodes::Stylesheet stylesheet, ?context: MediaQueries::Context) -> void
+
+    # Returns Hash<String, Declaration> of winning declarations after
+    # !important > inline > stylesheet > specificity > source-order
+    # sorting.
+    def resolve: (untyped element, ?inline_style: inline_style?) -> Hash[String, Nodes::Declaration]
+  end
+end

data/sig/css/media_queries.rbs

@@ -0,0 +1,107 @@
+module CSS
+  module MediaQueries
+    module Node
+    end
+
+    type modifier = :not | :only
+
+    type comparison_op = :eq | :lt | :le | :gt | :ge
+
+    type media_condition = MediaNot | MediaAnd | MediaOr | MediaFeature | GeneralEnclosed
+
+    type feature_value = Token | Ratio
+
+    class MediaQueryList < Data
+      include Node
+
+      attr_reader queries: Array[MediaQuery]
+
+      def self.new: (queries: Array[MediaQuery]) -> MediaQueryList
+    end
+
+    class MediaQuery < Data
+      include Node
+
+      attr_reader modifier: modifier?
+      attr_reader type: String?
+      attr_reader condition: media_condition?
+
+      def self.new: (modifier: modifier?, type: String?, condition: media_condition?) -> MediaQuery
+    end
+
+    class MediaNot < Data
+      include Node
+
+      attr_reader operand: media_condition
+
+      def self.new: (operand: media_condition) -> MediaNot
+    end
+
+    class MediaAnd < Data
+      include Node
+
+      attr_reader operands: Array[media_condition]
+
+      def self.new: (operands: Array[media_condition]) -> MediaAnd
+    end
+
+    class MediaOr < Data
+      include Node
+
+      attr_reader operands: Array[media_condition]
+
+      def self.new: (operands: Array[media_condition]) -> MediaOr
+    end
+
+    # `op` is `nil` for boolean form (`(color)`), `:eq` for plain
+    # (`(min-width: 600px)`) and explicit `=`, otherwise a comparison.
+    # `value` mirrors that — `nil` for boolean form.
+    class MediaFeature < Data
+      include Node
+
+      attr_reader name: String
+      attr_reader op: comparison_op?
+      attr_reader value: feature_value?
+
+      def self.new: (name: String, op: comparison_op?, value: feature_value?) -> MediaFeature
+    end
+
+    class GeneralEnclosed < Data
+      include Node
+
+      attr_reader tokens: Array[component_value]
+
+      def self.new: (tokens: Array[component_value]) -> GeneralEnclosed
+    end
+
+    class Ratio < Data
+      include Node
+
+      attr_reader numerator: Numeric
+      attr_reader denominator: Numeric
+
+      def self.new: (numerator: Numeric, denominator: Numeric) -> Ratio
+
+      def to_f: () -> Float
+    end
+
+    # User-agent context against which a `MediaQueryList` is evaluated.
+    # `features` is keyed by feature name (no `min-`/`max-` prefix);
+    # values follow Media Queries 4 conventions (lengths in CSS px,
+    # resolution in `dppx`, identifiers as Strings, booleans as 1/0).
+    class Context < Data
+      DEFAULTS: Hash[String, untyped]
+
+      attr_reader features: Hash[String, untyped]
+
+      def self.new: (features: Hash[String, untyped]) -> Context
+
+      # `Context.default('width' => 1200, 'prefers-color-scheme' => 'dark')`
+      def self.default: (**untyped overrides) -> Context
+
+      def []: ((String | Symbol) name) -> untyped
+      def media_type: () -> String
+      def with: (**untyped overrides) -> Context
+    end
+  end
+end

data/sig/css/nodes.rbs

@@ -0,0 +1,76 @@
+module CSS
+  module Nodes
+    # `Token` here covers preserved comments when the stylesheet was
+    # parsed with `preserve_comments: true`.
+    type rule = AtRule | QualifiedRule | Token
+
+    type block_item = Declaration | QualifiedRule | AtRule | Token
+
+    class Stylesheet < Data
+      attr_reader rules: Array[rule]
+
+      def self.new: (rules: Array[rule]) -> Stylesheet
+    end
+
+    # `prelude` is the list of component values before `{` or `;`;
+    # `block` is `nil` for at-rules ending with `;` (e.g. `@charset "UTF-8";`).
+    class AtRule < Data
+      attr_reader name: String
+      attr_reader prelude: Array[component_value]
+      attr_reader block: Block?
+
+      def self.new: (name: String, prelude: Array[component_value], block: Block?) -> AtRule
+    end
+
+    class QualifiedRule < Data
+      attr_reader prelude: Array[component_value]
+      attr_reader block: Block
+
+      def self.new: (prelude: Array[component_value], block: Block) -> QualifiedRule
+    end
+
+    class Block < Data
+      attr_reader items: Array[block_item]
+
+      def self.new: (items: Array[block_item]) -> Block
+    end
+
+    class Declaration < Data
+      attr_reader name: String
+      attr_reader value: Array[component_value]
+      attr_reader important: bool
+
+      def self.new: (name: String, value: Array[component_value], important: bool) -> Declaration
+    end
+
+    class Function < Data
+      attr_reader name: String
+      attr_reader value: Array[component_value]
+
+      def self.new: (name: String, value: Array[component_value]) -> Function
+    end
+
+    # `open` is one of `(`, `[`, `{`.
+    class SimpleBlock < Data
+      attr_reader open: String
+      attr_reader value: Array[component_value]
+
+      def self.new: (open: String, value: Array[component_value]) -> SimpleBlock
+
+      def braced?: () -> bool
+      def bracketed?: () -> bool
+      def parenthesized?: () -> bool
+    end
+
+    # Inclusive code-point range produced by `CSS.parse_urange`.
+    class UnicodeRange < Data
+      attr_reader first: Integer
+      attr_reader last: Integer
+
+      def self.new: (first: Integer, last: Integer) -> UnicodeRange
+
+      def cover?: (Integer cp) -> bool
+      def to_s: () -> String
+    end
+  end
+end

data/sig/css/selectors.rbs

@@ -0,0 +1,161 @@
+module CSS
+  module Selectors
+    # Marker module included by every Selector AST node so callers can
+    # discriminate `Selectors::Node` from raw component values.
+    module Node
+    end
+
+    type combinator = :descendant | :child | :next_sibling | :subsequent_sibling
+
+    type simple_selector =
+      TypeSelector | UniversalSelector | NestingSelector
+      | IdSelector | ClassSelector | AttributeSelector
+      | PseudoClass | PseudoElement
+
+    type attribute_matcher = :exact | :includes | :dash | :prefix | :suffix | :substring
+
+    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]
+
+    class SelectorList < Data
+      include Node
+
+      attr_reader selectors: Array[ComplexSelector]
+
+      def self.new: (selectors: Array[ComplexSelector]) -> SelectorList
+
+      def to_s: () -> String
+    end
+
+    # `compounds.size == combinators.size + 1`. `combinators[i]` joins
+    # `compounds[i]` to `compounds[i + 1]`.
+    class ComplexSelector < Data
+      include Node
+
+      attr_reader compounds: Array[CompoundSelector]
+      attr_reader combinators: Array[combinator]
+
+      def self.new: (compounds: Array[CompoundSelector], combinators: Array[combinator]) -> ComplexSelector
+
+      def to_s: () -> String
+    end
+
+    class CompoundSelector < Data
+      include Node
+
+      attr_reader components: Array[simple_selector]
+
+      def self.new: (components: Array[simple_selector]) -> CompoundSelector
+
+      def to_s: () -> String
+    end
+
+    class TypeSelector < Data
+      include Node
+
+      attr_reader name: String
+
+      def self.new: (name: String) -> TypeSelector
+    end
+
+    class UniversalSelector < Data
+      include Node
+
+      def self.new: () -> UniversalSelector
+    end
+
+    class NestingSelector < Data
+      include Node
+
+      def self.new: () -> NestingSelector
+    end
+
+    class IdSelector < Data
+      include Node
+
+      attr_reader name: String
+
+      def self.new: (name: String) -> IdSelector
+    end
+
+    class ClassSelector < Data
+      include Node
+
+      attr_reader name: String
+
+      def self.new: (name: String) -> ClassSelector
+    end
+
+    class AttributeSelector < Data
+      include Node
+
+      attr_reader name: String
+      attr_reader matcher: attribute_matcher?
+      attr_reader value: String?
+      attr_reader case_flag: case_flag?
+
+      def self.new: (name: String, matcher: attribute_matcher?, value: String?, case_flag: case_flag?) -> AttributeSelector
+    end
+
+    class PseudoClass < Data
+      include Node
+
+      attr_reader name: String
+      attr_reader argument: pseudo_argument
+
+      def self.new: (name: String, argument: pseudo_argument) -> PseudoClass
+    end
+
+    class PseudoElement < Data
+      include Node
+
+      attr_reader name: String
+      attr_reader argument: pseudo_argument
+
+      def self.new: (name: String, argument: pseudo_argument) -> PseudoElement
+    end
+
+    class AnB < Data
+      include Node
+
+      attr_reader step: Integer
+      attr_reader offset: Integer
+
+      def self.new: (step: Integer, offset: Integer) -> AnB
+
+      def to_s: () -> String
+    end
+
+    # Selectors §16 specificity tuple `(a, b, c)` — id / class+attr+pseudo /
+    # type+pseudo-element counts.
+    class Specificity < Data
+      include Comparable
+
+      ZERO: Specificity
+
+      attr_reader a: Integer
+      attr_reader b: Integer
+      attr_reader c: Integer
+
+      def self.new: (a: Integer, b: Integer, c: Integer) -> Specificity
+
+      def <=>: (untyped other) -> Integer?
+      def +: (Specificity other) -> Specificity
+      def to_s: () -> String
+    end
+
+    module Matcher
+      def self.matches?: (untyped element, untyped selector, ?cache: Hash[Integer, untyped]) -> bool
+
+      def self.tag_of: (untyped element, ?Hash[Integer, untyped]?) -> String
+      def self.id_of: (untyped element, ?Hash[Integer, untyped]?) -> String?
+      def self.classes_of: (untyped element, ?Hash[Integer, untyped]?) -> Set[String]
+    end
+  end
+end

data/sig/css/token.rbs

@@ -0,0 +1,33 @@
+module CSS
+  class Token
+    TYPES: Array[Symbol]
+
+    type token_type =
+      :ident | :function | :at_keyword | :hash | :string | :bad_string
+      | :url | :bad_url | :delim | :number | :percentage | :dimension
+      | :whitespace | :cdo | :cdc | :comment
+      | :colon | :semicolon | :comma
+      | :lbracket | :rbracket | :lparen | :rparen | :lbrace | :rbrace
+      | :eof
+
+    attr_reader type: token_type
+    attr_reader value: untyped
+    attr_reader flag: Symbol?
+    attr_reader unit: String?
+    attr_reader position: Position?
+
+    def initialize: (token_type type, ?untyped value, ?flag: Symbol?, ?unit: String?, ?position: Position?) -> void
+
+    def whitespace?: () -> bool
+    def comment?: () -> bool
+    def trivia?: () -> bool
+
+    def assign_position!: (Position pos) -> self
+
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+
+    def inspect: () -> String
+  end
+end

data/sig/css.rbs

@@ -0,0 +1,94 @@
+# CSS Syntax Level 4 toolkit — top-level entry points and shared types.
+#
+# Public API surface lives directly on `CSS`; AST nodes live under
+# `CSS::Nodes`, `CSS::Selectors`, and `CSS::MediaQueries`. Per-token
+# source positions are `CSS::Position`.
+module CSS
+  # Inputs that carry CSS source. `String` is tokenized internally; an
+  # array of component values (as produced by `CSS.parse_component_values`
+  # or by reading a rule's `prelude`) is consumed structurally.
+  type input = String | Array[component_value]
+
+  # The output of `CSS.parse_component_value` and the element type of a
+  # rule's `prelude` / declaration's `value`.
+  type component_value = Token | Nodes::Function | Nodes::SimpleBlock
+
+  # Bracket-pair information used by both the parser (open token type →
+  # open char, close token type) and the serializer.
+  BRACKET_OPEN_CHAR: Hash[Symbol, String]
+  BRACKET_CLOSE_TYPE: Hash[Symbol, Symbol]
+  BRACKET_PAIRS: Hash[String, String]
+
+  class ParseError < StandardError
+    attr_reader position: Position?
+
+    def initialize: (String message, ?position: Position?) -> void
+  end
+
+  # 1-based line / column with 0-based character offsets into the
+  # preprocessed input.
+  class Position < Data
+    attr_reader line: Integer
+    attr_reader column: Integer
+    attr_reader offset: Integer
+    attr_reader end_offset: Integer
+
+    def self.new: (line: Integer, column: Integer, offset: Integer, end_offset: Integer) -> Position
+
+    def to_s: () -> String
+  end
+
+  # Tokenization (Syntax 4 §4)
+  # ---------------------------------------------------------------
+
+  def self.tokenize: (String input, ?preserve_comments: bool) -> Array[Token]
+
+  # Parsing (Syntax 4 §5.3)
+  # ---------------------------------------------------------------
+
+  def self.parse_stylesheet: (input input, ?preserve_comments: bool) -> Nodes::Stylesheet
+  def self.parse: (input input, ?preserve_comments: bool) -> Nodes::Stylesheet
+
+  def self.parse_rule: (input input, ?preserve_comments: bool) -> (Nodes::AtRule | Nodes::QualifiedRule)
+  def self.parse_declaration: (input input, ?preserve_comments: bool) -> Nodes::Declaration
+  def self.parse_block_contents: (input input, ?preserve_comments: bool) -> Nodes::Block
+
+  def self.parse_component_value: (input input, ?preserve_comments: bool) -> component_value
+  def self.parse_component_values: (input input, ?preserve_comments: bool) -> Array[component_value]
+  def self.parse_comma_separated_values: (input input, ?preserve_comments: bool) -> Array[Array[component_value]]
+
+  # Selectors (Selectors 4)
+  # ---------------------------------------------------------------
+
+  def self.parse_selector_list: (String | Array[component_value] input) -> Selectors::SelectorList
+  def self.parse_selector: (String | Array[component_value] input) -> Selectors::ComplexSelector
+  def self.parse_anb: (String | Array[Token] input) -> Selectors::AnB
+
+  def self.specificity: (Selectors::Node selector) -> Selectors::Specificity
+
+  type selector = Selectors::SelectorList | Selectors::ComplexSelector | Selectors::CompoundSelector
+
+  def self.matches?: (untyped element, String | selector selector, ?cache: Hash[Integer, untyped]) -> bool
+
+  # Media queries (Media Queries 4)
+  # ---------------------------------------------------------------
+
+  def self.parse_media_query_list: (String | Array[component_value] input) -> MediaQueries::MediaQueryList
+
+  type media_context_input = MediaQueries::Context | Hash[String, untyped]
+
+  def self.media_matches?: (String | MediaQueries::MediaQueryList query_list, media_context_input context) -> bool
+
+  # Other transformations
+  # ---------------------------------------------------------------
+
+  def self.parse_urange: (_ToS input) -> Nodes::UnicodeRange
+
+  def self.desugar: (Nodes::Stylesheet stylesheet) -> Nodes::Stylesheet
+
+  def self.cascade: (Nodes::Stylesheet stylesheet, ?context: MediaQueries::Context) -> Cascade
+
+  def self.serialize: (untyped node) -> String
+
+  VERSION: String
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p_css
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Keita Urashima
@@ -45,6 +45,12 @@ files:
 - lib/css/urange.rb
 - lib/css/version.rb
 - lib/p_css.rb
+- sig/css.rbs
+- sig/css/cascade.rbs
+- sig/css/media_queries.rbs
+- sig/css/nodes.rbs
+- sig/css/selectors.rbs
+- sig/css/token.rbs
 homepage: https://github.com/ursm/p_css
 licenses:
 - MIT