roadie 2.4.3 → 3.0.0

data/lib/roadie/null_provider.rb

@@ -0,0 +1,13 @@
+module Roadie
+  # An asset provider that returns empty stylesheets for any name.
+  #
+  # Use it to ignore missing assets or in your tests when you need a provider
+  # but you do not care what it contains or that it is even referenced at all.
+  class NullProvider
+    def find_stylesheet(name) empty_stylesheet end
+    def find_stylesheet!(name) empty_stylesheet end
+
+    private
+    def empty_stylesheet() Stylesheet.new "(null)", "" end
+  end
+end

data/lib/roadie/null_url_rewriter.rb

@@ -0,0 +1,12 @@
+module Roadie
+  # @api private
+  # Null Object for the URL rewriter role.
+  #
+  # Used whenever client does not pass any URL options and no URL rewriting
+  # should take place.
+  class NullUrlRewriter
+    def initialize(generator = nil) end
+    def transform_dom(dom) end
+    def transform_css(css) end
+  end
+end

data/lib/roadie/provider_list.rb

@@ -0,0 +1,71 @@
+require 'forwardable'
+
+module Roadie
+  # An asset provider that just composes a list of other asset providers.
+  #
+  # Give it a list of providers and they will all be tried in order.
+  #
+  # {ProviderList} behaves like an Array, *and* an asset provider, and can be coerced into an array.
+  class ProviderList
+    extend Forwardable
+    include Enumerable
+    include AssetProvider
+
+    # Wrap a single provider, or a list of providers into a {ProviderList}.
+    #
+    # @overload wrap(provider_list)
+    #   @param [ProviderList] provider_list An actual instance of {ProviderList}.
+    #   @return The passed in provider_list
+    #
+    # @overload wrap(provider)
+    #   @param [asset provider] provider
+    #   @return a new {ProviderList} with just the passed provider in it
+    #
+    # @overload wrap(provider1, provider2, ...)
+    #   @return a new {ProviderList} with all the passed providers in it.
+    def self.wrap(*providers)
+      if providers.size == 1 && providers.first.class == self
+        providers.first
+      else
+        new(providers.flatten)
+      end
+    end
+
+    def initialize(providers)
+      @providers = providers
+    end
+
+    # @return [Stylesheet, nil]
+    def find_stylesheet(name)
+      @providers.each do |provider|
+        css = provider.find_stylesheet(name)
+        return css if css
+      end
+      nil
+    end
+
+    # ProviderList can be coerced to an array. This makes Array#flatten work
+    # with it, among other things.
+    def to_ary() to_a end
+
+    # @!method each
+    #   @see Array#each
+    # @!method size
+    #   @see Array#size
+    # @!method empty?
+    #   @see Array#empty?
+    # @!method push
+    #   @see Array#push
+    # @!method <<
+    #   @see Array#<<
+    # @!method pop
+    #   @see Array#pop
+    # @!method unshift
+    #   @see Array#unshift
+    # @!method shift
+    #   @see Array#shift
+    # @!method last
+    #   @see Array#last
+    def_delegators :@providers, :each, :size, :empty?, :push, :<<, :pop, :unshift, :shift, :last
+  end
+end

data/lib/roadie/rspec.rb

@@ -0,0 +1 @@
+require 'roadie/rspec/asset_provider'

data/lib/roadie/rspec/asset_provider.rb

@@ -0,0 +1,49 @@
+shared_examples_for "roadie asset provider" do |options|
+  valid_name = options[:valid_name] or raise "You must provide a :valid_name option to the shared examples"
+  invalid_name = options[:invalid_name] or raise "You must provide an :invalid_name option to the shared examples"
+
+  def verify_stylesheet(stylesheet)
+    expect(stylesheet).to_not be_nil
+
+    # Name
+    expect(stylesheet.name).to be_a(String)
+    expect(stylesheet.name).to_not be_empty
+
+    # We do not want to force clients to always return non-empty files.
+    # Stylesheet#initialize should crash when given a non-valid CSS (like nil,
+    # for example)
+    # expect(stylesheet.blocks).to_not be_empty
+  end
+
+  it "responds to #find_stylesheet" do
+    expect(subject).to respond_to(:find_stylesheet)
+    expect(subject.method(:find_stylesheet).arity).to eq 1
+  end
+
+  it "responds to #find_stylesheet!" do
+    expect(subject).to respond_to(:find_stylesheet!)
+    expect(subject.method(:find_stylesheet!).arity).to eq 1
+  end
+
+  describe "#find_stylesheet" do
+    it "can find a stylesheet" do
+      verify_stylesheet subject.find_stylesheet(valid_name)
+    end
+
+    it "cannot find an invalid stylesheet" do
+      expect(subject.find_stylesheet(invalid_name)).to be_nil
+    end
+  end
+
+  describe "#find_stylesheet!" do
+    it "can find a stylesheet" do
+      verify_stylesheet subject.find_stylesheet!(valid_name)
+    end
+
+    it "raises Roadie::CssNotFound on invalid stylesheets" do
+      expect {
+        subject.find_stylesheet!(invalid_name)
+      }.to raise_error Roadie::CssNotFound, Regexp.new(Regexp.quote(invalid_name))
+    end
+  end
+end

data/lib/roadie/selector.rb

@@ -1,24 +1,46 @@
 module Roadie
+  # @api private
+  #
+  # A selector is a domain object for a CSS selector, such as:
+  #   body
+  #   a:hover
+  #   input::placeholder
+  #   p:nth-of-child(4n+1) .important a img
+  #
+  # "Selectors" such as "strong, em" are actually two selectors and should be
+  # represented as two instances of this class.
+  #
+  # This class can also calculate specificity for the selector and answer a few
+  # questions about them.
+  #
+  # Selectors can be coerced into Strings, so they should be transparent to use
+  # anywhere a String is expected.
   class Selector
-    def initialize(selector)
+    def initialize(selector, specificity = nil)
       @selector = selector.to_s.strip
+      @specificity = specificity
     end
 
+    # Returns the specificity of the selector, calculating it if needed.
     def specificity
       @specificity ||= CssParser.calculate_specificity selector
     end
 
+    # Returns whenever or not a selector can be inlined.
+    # It's impossible to inline properties that applies to a pseudo element
+    # (like +::placeholder+, +::before+) or a pseudo function (like +:active+).
+    #
+    # We cannot inline styles that appear inside "@" constructs, like +@keyframes+.
     def inlinable?
       !(pseudo_element? || at_rule? || pseudo_function?)
     end
 
-    def to_s
-      selector
-    end
-
+    def to_s() selector end
     def to_str() to_s end
     def inspect() selector.inspect end
 
+    # {Selector}s are equal to other {Selector}s if, and only if, their string
+    # representations are equal.
     def ==(other)
       if other.is_a?(self.class)
         other.selector == selector
@@ -28,23 +50,26 @@ module Roadie
     end
 
     protected
-      attr_reader :selector
+    attr_reader :selector
 
     private
-      BAD_PSEUDO_FUNCTIONS = %w[:active :focus :hover :link :target :visited
-                                :-ms-input-placeholder :-moz-placeholder
-                                :before :after :enabled :disabled :checked].freeze
+    BAD_PSEUDO_FUNCTIONS = %w[
+      :active :focus :hover :link :target :visited
+      :-ms-input-placeholder :-moz-placeholder
+      :before :after
+      :enabled :disabled :checked
+    ].freeze
 
-      def pseudo_element?
-        selector.include? '::'
-      end
+    def pseudo_element?
+      selector.include? '::'
+    end
 
-      def at_rule?
-        selector[0, 1] == '@'
-      end
+    def at_rule?
+      selector[0, 1] == '@'
+    end
 
-      def pseudo_function?
-        BAD_PSEUDO_FUNCTIONS.any? { |bad| selector.include?(bad) }
-      end
+    def pseudo_function?
+      BAD_PSEUDO_FUNCTIONS.any? { |bad| selector.include?(bad) }
+    end
   end
 end

data/lib/roadie/style_attribute_builder.rb

@@ -0,0 +1,25 @@
+module Roadie
+  class StyleAttributeBuilder
+    def initialize
+      @styles = []
+    end
+
+    def <<(style)
+      @styles << style
+    end
+
+    def attribute_string
+      stable_sort(@styles).map(&:to_s).join(';')
+    end
+
+    private
+    def stable_sort(list)
+      # Ruby's sort is unstable for performance reasons. We need it to be
+      # stable, e.g. to preserve order of elements that are compared equal in
+      # the sorting.
+      # We can accomplish this by using the original array index as a second
+      # comparator for when the first one is equal.
+      list.each_with_index.sort_by { |item, index| [item, index] }.map(&:first)
+    end
+  end
+end

data/lib/roadie/style_block.rb

@@ -0,0 +1,32 @@
+require 'forwardable'
+
+module Roadie
+  # @api private
+  # A style block is the combination of a {Selector} and a list of {StyleProperty}.
+  class StyleBlock
+    extend Forwardable
+    attr_reader :selector, :properties
+
+    # @param [Selector] selector
+    # @param [Array<StyleProperty>] properties
+    def initialize(selector, properties)
+      @selector = selector
+      @properties = properties
+    end
+
+    # @!method specificity
+    #   @see Selector#specificity
+    # @!method inlinable?
+    #   @see Selector#inlinable?
+    def_delegators :selector, :specificity, :inlinable?
+    # @!method selector_string
+    #   @see Selector#to_s
+    def_delegator :selector, :to_s, :selector_string
+
+    # String representation of the style block. This is valid CSS and can be
+    # used in the DOM.
+    def to_s
+      "#{selector}{#{properties.map(&:to_s).join(';')}}"
+    end
+  end
+end

data/lib/roadie/style_property.rb

@@ -0,0 +1,93 @@
+module Roadie
+  # @api private
+  # Domain object for a CSS property such as "color: red !important".
+  #
+  # @attr_reader [String] property name of the property (such as "font-size").
+  # @attr_reader [String] value value of the property (such as "5px solid green").
+  # @attr_reader [Boolean] important if the property is "!important".
+  # @attr_reader [Integer] specificity specificity of parent {Selector}. Used to compare/sort.
+  class StyleProperty
+    include Comparable
+
+    attr_reader :value, :important, :specificity
+
+    # @todo Rename #property to #name
+    attr_reader :property
+
+    # Parse a property string.
+    #
+    # @example
+    #   property = Roadie::StyleProperty.parse("color: green")
+    #   property.property # => "color"
+    #   property.value # => "green"
+    #   property.important? # => false
+    def self.parse(declaration, specificity)
+      allocate.send :read_declaration!, declaration, specificity
+    end
+
+    def initialize(property, value, important, specificity)
+      @property = property
+      @value = value
+      @important = important
+      @specificity = specificity
+    end
+
+    def important?
+      @important
+    end
+
+    # Compare another {StyleProperty}. Important styles are "greater than"
+    # non-important ones; otherwise the specificity declares order.
+    def <=>(other)
+      if important == other.important
+        specificity <=> other.specificity
+      else
+        important ? 1 : -1
+      end
+    end
+
+    def to_s
+      [property, value_with_important].join(':')
+    end
+
+    def inspect
+      "#{to_s} (#{specificity})"
+    end
+
+    protected
+    def read_declaration!(declaration, specificity)
+      if (matches = DECLARATION_MATCHER.match(declaration))
+        initialize matches[:property], matches[:value].strip, !!matches[:important], specificity
+        self
+      else
+        raise UnparseableDeclaration, "Cannot parse declaration #{declaration.inspect}"
+      end
+    end
+
+    private
+    DECLARATION_MATCHER = %r{
+      \A\s*
+      (?:
+        # !important declaration
+        (?<property>[^:]+):\s?
+        (?<value>.*?)
+        (?<important>\s!important)
+        ;?
+      |
+        # normal declaration
+        (?<property>[^:]+):\s?
+        (?<value>[^;]+)
+        ;?
+      )
+      \s*\Z
+    }x.freeze
+
+    def value_with_important
+      if important
+        "#{value} !important"
+      else
+        value
+      end
+    end
+  end
+end

data/lib/roadie/stylesheet.rb

@@ -0,0 +1,65 @@
+module Roadie
+  # Domain object that represents a stylesheet (from disc, perhaps).
+  #
+  # It has a name and a list of {StyleBlock}s.
+  #
+  # @attr_reader [String] name the name of the stylesheet ("stylesheets/main.css", "Admin user styles", etc.). The name of the stylesheet will be visible if any errors occur.
+  # @attr_reader [Array<StyleBlock>] blocks
+  class Stylesheet
+    attr_reader :name, :blocks
+
+    # Parses the CSS string into a {StyleBlock}s and stores it.
+    #
+    # @param [String] name
+    # @param [String] css
+    def initialize(name, css)
+      @name = name
+      @blocks = parse_blocks(css)
+    end
+
+    # @yield [selector, properties]
+    # @yieldparam [Selector] selector
+    # @yieldparam [Array<StyleProperty>] properties
+    def each_inlinable_block(&block)
+      # #map and then #each in order to support chained enumerations, etc. if
+      # no block is provided
+      inlinable_blocks.map { |style_block|
+        [style_block.selector, style_block.properties]
+      }.each(&block)
+    end
+
+    def to_s
+      blocks.join("\n")
+    end
+
+    private
+    def inlinable_blocks
+      blocks.select(&:inlinable?)
+    end
+
+    def parse_blocks(css)
+      blocks = []
+      setup_parser(css).each_selector do |selector_string, declarations, specificity|
+        blocks << create_style_block(selector_string, declarations, specificity)
+      end
+      blocks
+    end
+
+    def create_style_block(selector_string, declarations, specificity)
+      StyleBlock.new(
+        Selector.new(selector_string, specificity),
+        parse_declarations(declarations, specificity)
+      )
+    end
+
+    def setup_parser(css)
+      parser = CssParser::Parser.new
+      parser.add_block! css
+      parser
+    end
+
+    def parse_declarations(declarations, specificity)
+      declarations.split(';').map { |declaration| StyleProperty.parse(declaration, specificity) }
+    end
+  end
+end