cataract 0.2.1 → 0.2.2

data/lib/cataract/stylesheet.rb

@@ -43,19 +43,30 @@ module Cataract
     #   - :base_path [String] Base directory for relative imports
     # @option options [Boolean] :io_exceptions (true) Whether to raise exceptions
     #   on I/O errors (file not found, network errors, etc.)
+    # @option options [Hash] :parser ({}) Parser configuration options
+    #   - :selector_lists [Boolean] (true) Track selector lists for W3C-compliant serialization
     def initialize(options = {})
       @options = {
         import: false,
-        io_exceptions: true
+        io_exceptions: true,
+        parser: {}
       }.merge(options)
 
+      # Parser options with defaults (stored for passing to parser)
+      @parser_options = {
+        selector_lists: true
+      }.merge(@options[:parser] || {})
+
       @rules = [] # Flat array of Rule structs
       @_media_index = {} # Hash: Symbol => Array of rule IDs
+      @_selector_lists = {} # Hash: list_id => Array of rule IDs (for "h1, h2" grouping)
+      @_next_selector_list_id = 0 # Counter for selector list IDs
       @charset = nil
       @imports = [] # Array of ImportStatement objects
       @_has_nesting = nil # Set by parser (nil or boolean)
       @_last_rule_id = nil # Tracks next rule ID for add_block
       @selectors = nil # Memoized cache of selectors
+      @_custom_properties = nil # Memoized cache of custom properties
     end
 
     # Initialize copy for proper deep duplication.
@@ -69,7 +80,10 @@ module Cataract
       @rules = source.instance_variable_get(:@rules).dup
       @imports = source.instance_variable_get(:@imports).dup
       @_media_index = source.instance_variable_get(:@_media_index).transform_values(&:dup)
-      @selectors = nil # Clear memoized cache
+      @_selector_lists = source.instance_variable_get(:@_selector_lists).transform_values(&:dup)
+      @_next_selector_list_id = source.instance_variable_get(:@_next_selector_list_id)
+      @parser_options = source.instance_variable_get(:@parser_options).dup
+      clear_memoized_caches
       @_hash = nil # Clear cached hash
     end
 
@@ -201,6 +215,7 @@ module Cataract
     #
     # @param property [String] CSS property name to match
     # @param value [String, nil] Optional property value to match
+    # @param prefix_match [Boolean] Whether to match by prefix (default: false)
     # @return [StylesheetScope] Scope with property filter applied
     #
     # @example Find all rules with color property
@@ -209,10 +224,13 @@ module Cataract
     # @example Find rules with position: absolute
     #   sheet.with_property('position', 'absolute').to_a
     #
+    # @example Find all margin-related properties (margin, margin-top, etc.)
+    #   sheet.with_property('margin', prefix_match: true).to_a
+    #
     # @example Chain with media filter
     #   sheet.with_media(:screen).with_property('z-index').to_a
-    def with_property(property, value = nil)
-      StylesheetScope.new(self, property: property, property_value: value)
+    def with_property(property, value = nil, prefix_match: false)
+      StylesheetScope.new(self, property: property, property_value: value, property_prefix_match: prefix_match)
     end
 
     # Filter to only base rules (rules not inside any @media query).
@@ -291,6 +309,46 @@ module Cataract
       @selectors ||= @rules.map(&:selector)
     end
 
+    # Get all custom property (CSS variable) definitions organized by media context.
+    #
+    # Returns a hash mapping media contexts to custom property hashes.
+    # Custom properties are CSS variables that start with -- (e.g., --primary-color).
+    # The :root key contains base-level properties (not inside any @media block).
+    # When the same custom property is defined multiple times within the same context,
+    # the last definition in source order is used.
+    #
+    # @param media [Symbol, Array<Symbol>, nil] Optional filter for specific media contexts
+    #   - nil (default) - Return all media contexts including :root
+    #   - :root - Return only base-level properties
+    #   - :print, :screen, etc. - Return only properties from specified media context(s)
+    #   - [:root, :print] - Return multiple contexts
+    #
+    # @return [Hash{Symbol => Hash{String => String}}] Media contexts mapped to custom properties
+    #
+    # @example All custom properties across all contexts
+    #   css = ':root { --color: red; } @media print { :root { --color: green; } }'
+    #   sheet = Cataract::Stylesheet.parse(css)
+    #   sheet.custom_properties #=> { :root => { '--color' => 'red' }, :print => { '--color' => 'green' } }
+    #
+    # @example Filter to specific media context
+    #   sheet.custom_properties(media: :print) #=> { :print => { '--color' => 'green' } }
+    #
+    # @example Filter to multiple contexts
+    #   sheet.custom_properties(media: [:root, :print]) #=> { :root => {...}, :print => {...} }
+    #
+    # @example Only base-level properties
+    #   css = ':root { --spacing: 8px; }'
+    #   sheet = Cataract::Stylesheet.parse(css)
+    #   sheet.custom_properties #=> { :root => { '--spacing' => '8px' } }
+    def custom_properties(media: nil)
+      @_custom_properties ||= build_custom_properties
+      return @_custom_properties if media.nil?
+
+      # Filter by media if requested
+      media_array = media.is_a?(Array) ? media : [media]
+      @_custom_properties.slice(*media_array)
+    end
+
     # Serialize to CSS string
     #
     # Converts the stylesheet to a CSS string. Optionally filters output
@@ -323,7 +381,7 @@ module Cataract
 
       # If :all is present, return everything (no filtering)
       if which_media_array.include?(:all)
-        Cataract._stylesheet_to_s(@rules, @_media_index, @charset, @_has_nesting || false)
+        Cataract._stylesheet_to_s(@rules, @_media_index, @charset, @_has_nesting || false, @_selector_lists)
       else
         # Collect all rule IDs that match the requested media types
         matching_rule_ids = []
@@ -347,7 +405,7 @@ module Cataract
 
         # C serialization with filtered data
         # Note: Filtered rules might still contain nesting, so pass the flag
-        Cataract._stylesheet_to_s(filtered_rules, filtered_media_index, @charset, @_has_nesting || false)
+        Cataract._stylesheet_to_s(filtered_rules, filtered_media_index, @charset, @_has_nesting || false, @_selector_lists)
       end
     end
     alias to_css to_s
@@ -380,7 +438,7 @@ module Cataract
 
       # If :all is present, return everything (no filtering)
       if which_media_array.include?(:all)
-        Cataract._stylesheet_to_formatted_s(@rules, @_media_index, @charset, @_has_nesting || false)
+        Cataract._stylesheet_to_formatted_s(@rules, @_media_index, @charset, @_has_nesting || false, @_selector_lists)
       else
         # Collect all rule IDs that match the requested media types
         matching_rule_ids = []
@@ -412,7 +470,7 @@ module Cataract
 
         # C serialization with filtered data
         # Note: Filtered rules might still contain nesting, so pass the flag
-        Cataract._stylesheet_to_formatted_s(filtered_rules, filtered_media_index, @charset, @_has_nesting || false)
+        Cataract._stylesheet_to_formatted_s(filtered_rules, filtered_media_index, @charset, @_has_nesting || false, @_selector_lists)
       end
     end
 
@@ -439,7 +497,7 @@ module Cataract
       @rules.clear
       @_media_index.clear
       @charset = nil
-      @selectors = nil # Clear memoized cache
+      clear_memoized_caches
       self
     end
 
@@ -600,8 +658,7 @@ module Cataract
       # Update rule IDs in remaining rules
       @rules.each_with_index { |rule, new_id| rule.id = new_id }
 
-      # Clear memoized cache
-      @selectors = nil
+      clear_memoized_caches
 
       self
     end
@@ -625,12 +682,28 @@ module Cataract
       offset = @_last_rule_id || 0
 
       # Parse CSS first (this extracts @import statements into result[:imports])
-      result = Cataract._parse_css(css)
+      result = Cataract._parse_css(css, @parser_options)
+
+      # Merge selector_lists with offsetted IDs
+      # Must do this BEFORE updating rule IDs so we can update rule.selector_list_id
+      list_id_offset = @_next_selector_list_id
+      if result[:_selector_lists] && !result[:_selector_lists].empty?
+        result[:_selector_lists].each do |list_id, rule_ids|
+          new_list_id = list_id + list_id_offset
+          offsetted_rule_ids = rule_ids.map { |id| id + offset }
+          @_selector_lists[new_list_id] = offsetted_rule_ids
+        end
+        @_next_selector_list_id = list_id_offset + result[:_selector_lists].size
+      end
 
       # Merge rules with offsetted IDs
       new_rules = result[:rules]
       new_rules.each do |rule|
         rule.id += offset
+        # Update selector_list_id to point to offsetted list (only for Rule, not AtRule)
+        if rule.is_a?(Rule) && rule.selector_list_id
+          rule.selector_list_id += list_id_offset
+        end
         @rules << rule
       end
 
@@ -675,6 +748,8 @@ module Cataract
       # Track if we have any nesting (for serialization optimization)
       @_has_nesting = result[:_has_nesting]
 
+      clear_memoized_caches
+
       self
     end
 
@@ -814,8 +889,7 @@ module Cataract
       other_has_nesting = other.instance_variable_get(:@_has_nesting)
       @_has_nesting = true if other_has_nesting
 
-      # Clear memoized cache
-      @selectors = nil
+      clear_memoized_caches
 
       # Apply cascade in-place
       flatten!
@@ -1006,6 +1080,55 @@ module Cataract
       end
     end
 
+    # Clear memoized caches that can be lazily rebuilt.
+    #
+    # Call this method after any operation that modifies the stylesheet's rules
+    # (e.g., add_block, remove_rules, merge). These caches will automatically
+    # rebuild on next access.
+    #
+    # Clears:
+    # - @selectors: Memoized list of all selectors
+    # - @_custom_properties: Memoized custom properties organized by media context
+    #
+    # Should not add ivars here that don't rebuild themselves (i.e. @_media_index)
+    def clear_memoized_caches
+      @selectors = nil
+      @_custom_properties = nil
+    end
+
+    # Build custom properties hash organized by media context
+    #
+    # @return [Hash{Symbol => Hash{String => String}}] Media contexts mapped to custom properties
+    def build_custom_properties
+      props_by_media = {}
+
+      # Build reverse lookup: rule_id => media_type
+      rule_id_to_media = {}
+      @_media_index.each do |media_type, rule_ids|
+        rule_ids.each do |rule_id|
+          rule_id_to_media[rule_id] = media_type
+        end
+      end
+
+      # Collect custom properties from each rule
+      @rules.each do |rule|
+        next unless rule.selector? # Skip at-rules
+
+        # Determine media context (:root for base-level rules)
+        media_context = rule_id_to_media[rule.id] || :root
+
+        # Collect custom properties from this rule
+        rule.declarations.each do |decl|
+          next unless decl.custom_property?
+
+          props_by_media[media_context] ||= {}
+          props_by_media[media_context][decl.property] = decl.value
+        end
+      end
+
+      props_by_media
+    end
+
     # Check if a rule has a declaration matching property and/or value
     #
     # @param rule [Rule] Rule to check (AtRule filtered out by each_selector)

data/lib/cataract/stylesheet_scope.rb

@@ -66,6 +66,7 @@ module Cataract
     #
     # @param property [String] CSS property name to match
     # @param value [String, nil] Optional property value to match
+    # @param prefix_match [Boolean] Whether to match by prefix (default: false)
     # @return [StylesheetScope] New scope with property filter applied
     #
     # @example Find rules with color property
@@ -74,8 +75,11 @@ module Cataract
     # @example Find rules with specific property value
     #   sheet.with_property('position', 'absolute')
     #   sheet.with_property('color', 'red')
-    def with_property(property, value = nil)
-      StylesheetScope.new(@stylesheet, @filters.merge(property: property, property_value: value))
+    #
+    # @example Find all margin-related properties (margin, margin-top, etc.)
+    #   sheet.with_property('margin', prefix_match: true)
+    def with_property(property, value = nil, prefix_match: false)
+      StylesheetScope.new(@stylesheet, @filters.merge(property: property, property_value: value, property_prefix_match: prefix_match))
     end
 
     # Filter to only base rules (rules not inside any @media query).
@@ -170,8 +174,11 @@ module Cataract
         end
 
         # Property filter
-        if @filters[:property] && !rule.has_property?(@filters[:property], @filters[:property_value])
-          next
+        if @filters[:property]
+          prefix_match = @filters.fetch(:property_prefix_match, false)
+          unless rule.has_property?(@filters[:property], @filters[:property_value], prefix_match: prefix_match)
+            next
+          end
         end
 
         # At-rule type filter

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - James Cook