cataract 0.2.3 → 0.2.5

data/lib/cataract/import_statement.rb

@@ -15,31 +15,55 @@ module Cataract
   #
   # @example Import with media query
   #   @import "mobile.css" screen and (max-width: 768px);
-  #   # => ImportStatement(url: "mobile.css", media: :"screen and (max-width: 768px)")
+  #   # => ImportStatement(url: "mobile.css", media_query_id: 0)
   #
   # @attr [Integer] id The import's position in the source (0-indexed)
   # @attr [String] url The URL to import (without quotes or url() wrapper)
-  # @attr [Symbol, nil] media The media query as a symbol, or nil if no media query
+  # @attr [String, nil] media The media query string (e.g., "print", "screen and (max-width: 768px)"), or nil
+  # @attr [Integer, nil] media_query_id The MediaQuery ID, or nil if no media query
   # @attr [Boolean] resolved Whether this import has been resolved/processed
-  ImportStatement = Struct.new(:id, :url, :media, :resolved) unless const_defined?(:ImportStatement)
+  ImportStatement = Struct.new(:id, :url, :media, :media_query_id, :resolved) unless const_defined?(:ImportStatement)
 
   class ImportStatement
+    # Factory method for creating ImportStatement in tests.
+    # Uses keyword arguments to avoid positional parameter confusion.
+    #
+    # @param id [Integer] Import ID (position in source)
+    # @param url [String] URL to import
+    # @param media [String, nil] Media query string (e.g., "print", "screen and (max-width: 768px)")
+    # @param media_query_id [Integer, nil] MediaQuery ID
+    # @param resolved [Boolean] Whether import has been resolved
+    # @return [ImportStatement] New import statement instance
+    #
+    # @example Create an import with keyword arguments
+    #   ImportStatement.make(
+    #     id: 0,
+    #     url: 'styles.css',
+    #     media: nil,
+    #     media_query_id: nil,
+    #     resolved: false
+    #   )
+    def self.make(id:, url:, media: nil, media_query_id: nil, resolved: false)
+      new(id, url, media, media_query_id, resolved)
+    end
+
     # Compare two ImportStatement objects for equality.
     # Two imports are equal if they have the same URL and media query.
-    # The ID is ignored as it's an implementation detail.
+    # The import ID is ignored as it's an implementation detail.
     #
     # @param other [Object] Object to compare with
     # @return [Boolean] true if equal, false otherwise
     def ==(other)
       return false unless other.is_a?(ImportStatement)
 
+      # Compare by media string (for unparsed imports) or media_query_id (for resolved imports)
       url == other.url && media == other.media
     end
 
     alias eql? ==
 
     # Generate hash code for ImportStatement.
-    # Uses URL and media query (ignores ID).
+    # Uses URL and media string (ignores import ID position).
     #
     # @return [Integer] Hash code
     def hash

data/lib/cataract/media_query.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Cataract
+  # MediaQuery represents a CSS media query constraint.
+  #
+  # Media queries are stored in the Stylesheet and referenced by Rules via media_query_id.
+  # This allows efficient tracking of which rules apply to which media contexts.
+  #
+  # @example Access media query properties
+  #   mq = MediaQuery.new(0, :screen, "(min-width: 768px)")
+  #   mq.id #=> 0
+  #   mq.type #=> :screen
+  #   mq.conditions #=> "(min-width: 768px)"
+  #   mq.text #=> "screen and (min-width: 768px)"
+  #
+  # @attr [Integer] id Unique identifier for this media query within the stylesheet
+  # @attr [Symbol] type Primary media type (:screen, :print, :all, etc.)
+  # @attr [String, nil] conditions Additional conditions like "(min-width: 768px)", or nil if none
+  MediaQuery = Struct.new(:id, :type, :conditions) do
+    # Create a MediaQuery with keyword arguments for readability.
+    #
+    # @param id [Integer] Unique ID for this media query
+    # @param type [Symbol] Primary media type
+    # @param conditions [String, nil] Optional conditions
+    # @return [MediaQuery] New media query instance
+    #
+    # @example Create a simple media query
+    #   MediaQuery.make(id: 0, type: :screen, conditions: nil)
+    #
+    # @example Create a media query with conditions
+    #   MediaQuery.make(id: 1, type: :screen, conditions: "(min-width: 768px)")
+    def self.make(id:, type:, conditions: nil)
+      new(id, type, conditions)
+    end
+
+    # Get the full media query text.
+    #
+    # Reconstructs the media query string from type and conditions.
+    #
+    # @return [String] Full media query text
+    #
+    # @example Simple media query
+    #   mq = MediaQuery.new(0, :screen, nil)
+    #   mq.text #=> "screen"
+    #
+    # @example Media query with conditions
+    #   mq = MediaQuery.new(0, :screen, "(min-width: 768px)")
+    #   mq.text #=> "screen and (min-width: 768px)"
+    def text
+      if conditions
+        # If type is :all, just return conditions (don't say "all and ...")
+        type == :all ? conditions : "#{type} and #{conditions}"
+      else
+        type.to_s
+      end
+    end
+
+    # Compare media queries for equality based on type and conditions.
+    #
+    # Two media queries are equal if they have the same type and conditions.
+    # IDs are not considered since they're internal identifiers.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if media queries match
+    def ==(other)
+      case other
+      when MediaQuery
+        type == other.type && conditions == other.conditions
+      else
+        false
+      end
+    end
+    alias_method :eql?, :==
+
+    # Generate hash code for this media query.
+    #
+    # Hash is based on type and conditions to match equality semantics.
+    #
+    # @return [Integer] hash code
+    def hash
+      [self.class, type, conditions].hash
+    end
+
+    # Get a human-readable representation.
+    #
+    # @return [String] String representation
+    def to_s
+      text
+    end
+
+    # Get detailed inspection string.
+    #
+    # @return [String] Inspection string
+    def inspect
+      "#<MediaQuery id=#{id} type=#{type.inspect} conditions=#{conditions.inspect}>"
+    end
+  end
+end

data/lib/cataract/pure/byte_constants.rb

@@ -46,11 +46,26 @@ module Cataract
   BYTE_BANG       = 33 # '!'
   BYTE_PERCENT    = 37 # '%'
   BYTE_SLASH_FWD  = 47 # '/' (also defined as BYTE_SLASH above)
+  BYTE_EQUALS     = 61 # '='
+  BYTE_CARET      = 94 # '^'
+  BYTE_DOLLAR     = 36 # '$'
+  BYTE_PIPE       = 124 # '|'
 
   # Specific lowercase letters (for keyword matching)
   BYTE_LOWER_U    = 117 # 'u'
   BYTE_LOWER_R    = 114 # 'r'
   BYTE_LOWER_L    = 108 # 'l'
+  BYTE_LOWER_D    = 100 # 'd'
+  BYTE_LOWER_T    = 116 # 't'
+  BYTE_LOWER_N    = 110 # 'n'
+
+  # Specific uppercase letters (for case-insensitive matching)
+  BYTE_UPPER_U    = 85  # 'U'
+  BYTE_UPPER_R    = 82  # 'R'
+  BYTE_UPPER_L    = 76  # 'L'
+  BYTE_UPPER_D    = 68  # 'D'
+  BYTE_UPPER_T    = 84  # 'T'
+  BYTE_UPPER_N    = 78  # 'N'
 
   # Letter ranges (a-z, A-Z)
   BYTE_LOWER_A   = 97  # 'a'

data/lib/cataract/pure/flatten.rb

@@ -2,6 +2,12 @@
 
 # Pure Ruby CSS flatten implementation
 # NO REGEXP ALLOWED - use string manipulation only
+#
+# @api private
+# This module contains internal methods for flattening CSS (merging rules with the
+# same selector, expanding/recreating shorthands). These methods are called by
+# Cataract.flatten and should not be used directly except for expand_shorthand
+# which is part of the public API. The main public API is Cataract.flatten.
 
 module Cataract
   module Flatten
@@ -115,6 +121,24 @@ module Cataract
     LIST_STYLE_PROPERTIES = [PROP_LIST_STYLE_TYPE, PROP_LIST_STYLE_POSITION, PROP_LIST_STYLE_IMAGE].freeze
     BORDER_ALL = (BORDER_WIDTHS + BORDER_STYLES + BORDER_COLORS).freeze
 
+    # Shorthand property lookup (Hash is faster than Array#include? or Set)
+    # Used for fast-path check to avoid calling expand_shorthand for non-shorthands
+    SHORTHAND_PROPERTIES = {
+      'margin' => true,
+      'padding' => true,
+      'border' => true,
+      'border-top' => true,
+      'border-right' => true,
+      'border-bottom' => true,
+      'border-left' => true,
+      'border-width' => true,
+      'border-style' => true,
+      'border-color' => true,
+      'font' => true,
+      'background' => true,
+      'list-style' => true
+    }.freeze
+
     # List style keywords
     LIST_STYLE_POSITION_KEYWORDS = %w[inside outside].freeze
 
@@ -154,27 +178,47 @@ module Cataract
       # Expand shorthands in regular rules only (AtRules don't have declarations)
       # NOTE: Using manual each + concat instead of .flat_map for performance.
       # The concise form (.flat_map) is ~5-10% slower depending on number of shorthands to expand.
+      # NOTE: Fast-path check for shorthands (Hash lookup) avoids calling expand_shorthand
+      # for declarations that are not shorthands (~20% faster than calling method unconditionally).
       regular_rules.each do |rule|
         expanded = []
         rule.declarations.each do |decl|
-          expanded.concat(_expand_shorthand(decl))
+          if SHORTHAND_PROPERTIES[decl.property]
+            expanded.concat(expand_shorthand(decl))
+          else
+            expanded << decl
+          end
         end
         rule.declarations.replace(expanded)
       end
 
       merged_rules = []
 
-      # Always group by selector and preserve original selectors
-      # (Nesting is flattened during parsing, so we just merge by resolved selector)
+      # Group by (selector, media_query_id) instead of just selector
+      # Rules with same selector but different media contexts should NOT be merged
       # NOTE: Using manual each instead of .group_by to avoid intermediate hash allocation.
-      # The concise form (.group_by) is ~10-25% slower depending on selector uniqueness.
-      by_selector = {}
+      by_selector_and_media = {}
       regular_rules.each do |rule|
-        (by_selector[rule.selector] ||= []) << rule
+        media_query_id = rule.media_query_id
+        key = [rule.selector, media_query_id]
+        (by_selector_and_media[key] ||= []) << rule
       end
-      by_selector.each do |selector, rules|
-        merged_rule = flatten_rules_for_selector(selector, rules)
-        merged_rules << merged_rule if merged_rule
+
+      # Track old rule ID to new merged rule index mapping (only for rules in media queries)
+      old_to_new_id = {}
+      by_selector_and_media.each do |(_selector, media_query_id), rules|
+        merged_rule = flatten_rules_for_selector(rules.first.selector, rules)
+        next unless merged_rule
+
+        # Only build mapping for rules that are in media queries
+        if media_query_id
+          new_index = merged_rules.length
+
+          rules.each do |old_rule|
+            old_to_new_id[old_rule.id] = new_index
+          end
+        end
+        merged_rules << merged_rule
       end
 
       # Recreate shorthands where possible
@@ -195,11 +239,55 @@ module Cataract
       # Add passthrough AtRules to output
       merged_rules.concat(at_rules)
 
+      # Rebuild media_index from rules' media_query_id
+      # This ensures media_index is consistent with the MediaQuery objects
+      media_queries = stylesheet.instance_variable_get(:@media_queries)
+      media_query_lists = stylesheet.instance_variable_get(:@_media_query_lists)
+      new_media_index = {}
+
+      # Build reverse map: media_query_id => list_id (one-time cost)
+      mq_id_to_list_id = {}
+      media_query_lists.each do |list_id, mq_ids|
+        mq_ids.each { |mq_id| mq_id_to_list_id[mq_id] = list_id }
+      end
+
+      merged_rules.each do |rule|
+        next unless rule.is_a?(Rule) && rule.media_query_id
+
+        # Check if this rule's media_query_id is part of a list
+        list_id = mq_id_to_list_id[rule.media_query_id]
+
+        if list_id
+          # This rule is in a compound media query (e.g., "@media screen, print")
+          # Index it under ALL media types in the list
+          mq_ids = media_query_lists[list_id]
+          mq_ids.each do |mq_id|
+            mq = media_queries[mq_id]
+            next unless mq
+
+            media_type = mq.type
+            new_media_index[media_type] ||= []
+            new_media_index[media_type] << rule.id
+          end
+        else
+          # Single media query - just index under its type
+          mq = media_queries[rule.media_query_id]
+          next unless mq
+
+          media_type = mq.type
+          new_media_index[media_type] ||= []
+          new_media_index[media_type] << rule.id
+        end
+      end
+
+      # Deduplicate arrays once at the end
+      new_media_index.each_value(&:uniq!)
+
       # Create result stylesheet
       if mutate
         stylesheet.instance_variable_set(:@rules, merged_rules)
-        # Clear media index (no media rules after merge flattens everything)
-        stylesheet.instance_variable_set(:@media_index, {})
+        stylesheet.instance_variable_set(:@media_index, new_media_index)
+        # @media_queries and @_media_query_lists stay the same - preserved from input
         # Update selector lists with divergence tracking
         stylesheet.instance_variable_set(:@_selector_lists, selector_lists)
         stylesheet
@@ -207,7 +295,9 @@ module Cataract
         # Create new Stylesheet with merged rules
         result = Stylesheet.new
         result.instance_variable_set(:@rules, merged_rules)
-        result.instance_variable_set(:@media_index, {})
+        result.instance_variable_set(:@media_index, new_media_index)
+        result.instance_variable_set(:@media_queries, media_queries)
+        result.instance_variable_set(:@_media_query_lists, media_query_lists)
         result.instance_variable_set(:@charset, stylesheet.charset)
         result.instance_variable_set(:@_selector_lists, selector_lists)
         result
@@ -294,6 +384,9 @@ module Cataract
       selector_list_ids.uniq!
       selector_list_id = selector_list_ids.size == 1 ? selector_list_ids.first : nil
 
+      # All rules being merged have the same media_query_id (they were grouped by it)
+      media_query_id = rules.first.media_query_id
+
       # Create merged rule
       Rule.new(
         0, # ID will be updated later
@@ -302,7 +395,8 @@ module Cataract
         rules.first.specificity, # Use first rule's specificity
         nil,  # No parent after flattening
         nil,  # No nesting style after flattening
-        selector_list_id # Preserve if all rules share same ID
+        selector_list_id, # Preserve if all rules share same ID
+        media_query_id # Preserve media context
       )
     end
 
@@ -321,7 +415,7 @@ module Cataract
     # @param decl [Declaration] Declaration to expand
     # @return [Array<Declaration>] Array of expanded longhand declarations
     # @api private
-    def self._expand_shorthand(decl)
+    def self.expand_shorthand(decl)
       case decl.property
       when 'margin'
         expand_margin(decl)
@@ -1133,7 +1227,13 @@ module Cataract
         parts << attachment if attachment
       end
 
-      shorthand_value = parts.join(' ')
+      # If all properties are defaults, the shorthand value would be empty
+      # In this case, use "none" which is equivalent to all-default background
+      shorthand_value = if parts.empty?
+                          'none'
+                        else
+                          parts.join(' ')
+                        end
 
       # Remove individual properties and append shorthand
       # Note: We append rather than insert at original position to match C implementation behavior
@@ -1236,5 +1336,17 @@ module Cataract
           d1.important == d2.important
       end
     end
+
+    # Mark all methods except flatten and expand_shorthand as private
+    private_class_method :flatten_rules_for_selector, :calculate_specificity,
+                         :expand_margin, :expand_padding, :parse_four_sides, :split_on_whitespace,
+                         :expand_border, :expand_border_side, :expand_border_width, :expand_border_style,
+                         :expand_border_color, :parse_border_value, :is_border_width?, :is_border_style?,
+                         :expand_font, :is_font_size?, :is_font_style?, :is_font_variant?, :is_font_weight?,
+                         :expand_background, :starts_with_url?, :is_position_value?, :expand_list_style,
+                         :recreate_shorthands!, :recreate_margin!, :recreate_padding!, :check_all_same?,
+                         :recreate_border!, :recreate_border_width!, :recreate_border_style!, :recreate_border_color!,
+                         :optimize_four_sides, :recreate_font!, :recreate_background!, :recreate_list_style!,
+                         :update_selector_lists_for_divergence!, :declarations_equal?
   end
 end