archetype 0.0.1.pre.13 → 1.0.0.alpha.1

data/lib/archetype/functions/css/helpers.rb

@@ -0,0 +1,265 @@
+module Archetype::Functions::CSS
+
+  private
+
+  #
+  # output a warning about a disambiguous property found that can't be fully derived
+  #
+  # *Parameters*:
+  # - <tt>property</tt> {String} the property
+  # - <tt>info</tt> {String} additional info to display
+  #
+  def self.warn_cannot_disambiguate_property(property, info = nil)
+    info = (info.nil? or info.empty?) ? '' : " (#{info})"
+    return warn("[#{Archetype.name}:css:derive] cannot disambiguate the CSS property `#{property}#{info}`")
+  end
+
+  #
+  # output a warning if there isn't enough information to derive the value requested
+  #
+  # *Parameters*:
+  # - <tt>property</tt> {String} the property
+  # *Returns*:
+  # - {Sass::Null}
+  #
+  def self.warn_not_enough_infomation_to_derive(property)
+    return warn("[#{Archetype.name}:css:derive] there isn't enough information to derive `#{property}`, so returning `null`")
+  end
+
+  #
+  # checks to see if a property is the root property or a descendent
+  #
+  # *Returns*:
+  # - {Boolean} true if the property is a root property
+  # *Returns*:
+  # - {Sass::Null}
+  #
+  def self.is_root_property?(property)
+    special_roots = %w(list-style border-image border-radius)
+    return special_roots.push(get_property_base(property)).include?(property)
+  end
+
+  #
+  # given a set of related properties, get the set of properties that are currently available
+  #
+  # *Parameters*:
+  # - <tt>related</tt> {Hash} the hash of styles
+  # - <tt>property</tt> {String} the property to observe
+  # *Returns*:
+  # - {Hash} the available related properties and their values
+  #
+  def self.filter_available_relatives(related, property)
+    handler = "filter_available_relatives_for_#{get_property_base(property)}"
+    # handle special cases like `border`
+    if self.respond_to?(handler)
+      set = self.method(handler).call(related, property)
+    else
+      set = Set.new
+      previous = nil
+      # find all potential parents (and self)
+      property.split('-').each do |value|
+        value = previous.nil? ? value : "#{previous}-#{value}"
+        set << value
+        previous = value
+      end
+      base = /(?:^|\s)#{Regexp.escape(property)}-[^\s]+(?:$|\s)/
+      related.each do |key, value|
+        set << key if key =~ base
+      end
+    end
+    return related.select { |key, value| set.include?(key) }
+  end
+
+  #
+  # filter relatives for `border`
+  #
+  def self.filter_available_relatives_for_border(related, property)
+    set = Set.new
+    set << property
+    case property
+    # border-radius and border-image
+    when R_BORDER_IMG_OR_RADIUS
+      match = $1
+      if property == "border-#{match}" or match == 'radius'
+        pattern = /^border-.*#{match}/
+        ALL_CSS_PROPERTIES.each { |k,v| set << k if k =~ pattern }
+      else
+        set << "border-#{match}"
+      end
+    when R_BORDER_STD
+      pattern = R_BORDER_STD
+      if property != 'border'
+        position, type = $1, $2
+        if position
+          if type
+            # position and type
+            # e.g. for border-top-width
+            # we'll need: border, border-top, border-top-width, border-width
+            pattern = /^(border|border#{position}(#{type})?$|border#{type})$/
+          else
+            # position only
+            # e.g. for border-top
+            # we'll need: border, border-top, border-top-{type}, border-{type}
+            pattern = /^(border|border#{position}#{RS_BORDER_TYPE}?$|border#{RS_BORDER_TYPE})$/
+          end
+        else
+          # type only
+          # e.g. for border-width
+          # we'll need: border, border-width, border-{position}-width, border-{position}
+          pattern = /^(border|border#{RS_BORDER_POSITION}?#{type}$|border#{RS_BORDER_POSITION})$/
+        end
+      end
+      ALL_CSS_PROPERTIES.each { |k,v| set << k if k =~ pattern }
+    end
+    return set
+  end
+
+  #
+  # for each item in a given style object, if the value is an array, convert it to a Sass::List
+  #
+  # *Parameters*:
+  # - <tt>styles</tt> {Hash} the styles
+  # - <tt>separator</tt> {Symbol} the separator to use on the generated list
+  # *Returns*:
+  # - {Hash} the styles hash with updated values
+  #
+  def self.collapse_multi_value_lists(styles, separator = :space)
+    styles.each do |key, value|
+      if value.is_a?(Array)
+        # if all the values are identical, we just need to return one
+        styles[key] = value.uniq.length == 1 ? value.first : Sass::Script::Value::List.new(value, separator)
+      end
+    end
+    return styles
+  end
+
+  #
+  # normalizes the property into a key for use on a hash
+  #
+  # *Parameters*:
+  # - <tt>property</tt> {String} the property to be used as a key
+  # - <tt>base</tt> {String} the base of the property
+  # *Returns*:
+  # - {Symbol} the property normalized as a symbol
+  #
+  def self.normalize_property_key(property, base = nil)
+    base ||= get_property_base(property)
+    return property.gsub(/^#{Regexp.escape(base)}\-/, '').gsub('-', '_').to_sym
+  end
+
+  #
+  # gets the base of a property
+  #
+  # *Parameters*:
+  # - <tt>property</tt> {String} the property
+  # *Returns*:
+  # - {String} the base of the property
+  #
+  def self.get_property_base(property)
+    return (property.match(/^([a-z]+)/) || [])[0]
+  end
+
+  #
+  # extracts potential timing values from an array of values
+  #
+  # *Parameters*:
+  # - <tt>value</tt> {Array} an array of Sass values
+  # *Returns*:
+  # - {Array} the extracted timing values
+  #
+  def self.get_timing_values(value)
+    return value.select do |item|
+      if item.is_a?(Sass::Script::Value::Number)
+        unit = helpers.to_str(item.unit_str)
+        ((item.unitless? and item.value == 0) or unit.include?('s'))
+      end
+    end
+  end
+
+  #
+  # helper to iterate over each available relative property
+  #
+  # *Parameters*:
+  # - <tt>related</tt> {Hash} the hash of styles
+  # - <tt>property</tt> {String} the property to observe
+  #
+  def self.with_each_available_relative(related, property)
+    filter_available_relatives(related, property).each do |key, value|
+      yield(key, value) if block_given?
+    end
+  end
+
+  #
+  # helper to iterate over each available relative property, and executes a block if the property is a root property
+  #
+  # *Parameters*:
+  # - <tt>related</tt> {Hash} the hash of styles
+  # - <tt>property</tt> {String} the property to observe
+  # *Returns*:
+  # - {Hash} augmented styles hash
+  #
+  def self.with_each_available_relative_if_root(related, property)
+    styles = ::Archetype::Hash.new
+    augmented = false
+    with_each_available_relative(related, property) do |key, value|
+      styles[normalize_property_key(key)] = value
+      augmented = !is_root_property?(key)
+      # if it's the shorthand property...
+      if !augmented
+        styles = yield(value.to_a.dup, (value.is_a?(Sass::Script::Value::List) && value.separator == :comma)) if block_given?
+      end
+    end
+    return styles, (augmented && is_root_property?(property))
+  end
+
+  #
+  # given a styles object, sets default values for each property if not already set
+  #
+  # *Parameters*:
+  # - <tt>styles</tt> {Hash} the styles
+  # - <tt>base</tt> {String} the base string
+  # - <tt>properties</tt> {Array} the properties to default if not set
+  # *Returns*:
+  # - {Hash} augmented styles hash
+  #
+  def self.set_default_styles(styles, base, properties)
+    properties.each { |k| styles[normalize_property_key(k, base)] ||= default("#{base}-#{k}") }
+    return styles
+  end
+
+  #
+  # given a list of symmetrical values, extracts the [top right bottom left] key-value pairs
+  #
+  # *Parameters*:
+  # - <tt>items</tt> {Array} the items
+  # *Returns*:
+  # - {Hash} the hash of [top right bottom left]
+  #
+  def self.extract_symmetical_values(items)
+    return {
+      :top        => items[0],
+      :right      => items[1] || items[0],
+      :bottom     => items[2] || items[0],
+      :left       => items[3] || items[1] || items[0]
+    }
+  end
+
+  #
+  # wrapper to display a warning and return Sass::Null
+  #
+  # *Parameters*:
+  # - <tt>msg</tt> {String} the message to display
+  # *Returns*:
+  # - {Sass::Null}
+  #
+  def self.warn(msg)
+    helpers.warn msg
+    return Sass::Script::Value::Null.new
+  end
+
+  # shortcut to Archetype::Functions::Helpers
+  def self.helpers
+    Archetype::Functions::Helpers
+  end
+
+end

data/lib/archetype/functions/css/routers.rb

@@ -0,0 +1,28 @@
+module Archetype::Functions::CSS
+
+  private
+
+  #
+  # given a set of related properties, compute the property value
+  #
+  # *Parameters*:
+  # - <tt>hsh</tt> {Hash} the hash of styles
+  # - <tt>property</tt> {String} the original property we're looking for
+  # *Returns*:
+  # - {Hash} the derived styles
+  #
+  def self.get_derived_styles_via_router(hsh, property)
+    base = get_property_base(property)
+    handler = "get_derived_styles_router_for_#{base}"
+    # if we don't need any additional processing, stop here
+    return nil if not self.respond_to?(handler)
+    base = /^#{base}/
+    value = self.method(handler).call(hsh.select { |key, value| key =~ base }, property)
+    value = value[normalize_property_key(property)] if value.is_a?(Hash)
+    return value
+  end
+end
+
+%w(animation background border list margin_padding outline overflow target transition).each do |router|
+  require "archetype/functions/css/routers/#{router}"
+end

data/lib/archetype/functions/css/routers/animation.rb

@@ -0,0 +1,55 @@
+module Archetype::Functions::CSS
+
+  private
+
+  #
+  # router for `animiation` properties
+  #
+  def self.get_derived_styles_router_for_animation(related, property)
+    properties = %w(name duration timing-function delay iteration-count direction play-state)
+    styles, reconstruct = with_each_available_relative_if_root(related, property) do |items, comma_separated|
+      # blow away anything we've already discovered (because it's irrelevant)
+      # identify the items that are timing units
+      timings = get_timing_values(items)
+      items = items - timings
+      # name duration timing-function delay iteration-count direction
+      styles = ::Archetype::Hash.new
+      styles[:duration] = timings.shift
+      styles[:delay]    = timings.shift
+      items.reject! do |item|
+        case helpers.to_str(item)
+        when /^(?:normal|alternate|reverse|alternate-reverse)$/
+          styles[:direction] = item
+        when /^(?:none|forwards|backwards|both)$/
+          styles[:fill_mode] = item
+        when /^(?:running|paused)$/
+          styles[:play_state] = item
+        when /^(?:[\d\.]+|infinite)$/
+          styles[:iteration_count] = item
+        when R_TIMING_FUNCTION
+          styles[:timing_function] = item
+        else
+          next
+        end
+        true
+      end
+      styles[:name] = items.shift
+      styles[:timing_function] = items.shift
+      # set defaults if we missed anything...
+      styles = set_default_styles(styles, 'animation', properties)
+      # make the styles available to the calling context
+      styles
+    end
+
+    if reconstruct
+      value = extrapolate_shorthand_animation(styles)
+      # if the value came back nil, we were missing something, so throw a warning...
+      return warn_not_enough_infomation_to_derive(property) if value.nil?
+      return value
+    end
+
+    # otherwise just return the value we were asked for
+    return styles
+  end
+
+end

data/lib/archetype/functions/css/routers/background.rb

@@ -0,0 +1,38 @@
+module Archetype::Functions::CSS
+
+  private
+
+  #
+  # router for `background` properties
+  #
+  def self.get_derived_styles_router_for_background(related, property)
+    properties = %w(color position size repeat origin clip attachment image)
+    property_order = [:color, :position, :size, :repeat, :origin, :clip, :attachment, :image]
+
+    styles, reconstruct = with_each_available_relative_if_root(related, property) do |items, comma_separated|
+      deconstruct_shorthand_for_background(items, comma_separated, properties)
+    end
+
+    if reconstruct
+      return warn_not_enough_infomation_to_derive(property) if styles.nil?
+
+      shorthands = []
+      total = 1
+      styles.each do |key, value|
+        total = value.length if value.is_a?(Array) && value.length > total
+      end
+      total.times do |i|
+        shorthand = []
+        properties.each { |k| shorthand << (styles[k.to_sym].is_a?(Array) ? styles[k.to_sym][i] : styles[k.to_sym]) || default("background-#{k}") }
+        shorthands << Sass::Script::Value::List.new(shorthand, :space)
+      end
+      return Sass::Script::Value::List.new(shorthands, :comma)
+    end
+
+    # collapse any multi-background values we got
+    styles = collapse_multi_value_lists(styles, :comma)
+
+    # otherwise just return the value we were asked for
+    return styles
+  end
+end

data/lib/archetype/functions/css/routers/border.rb

@@ -0,0 +1,151 @@
+module Archetype::Functions::CSS
+
+  private
+
+  #
+  # router for `border` and `border-{position}`
+  #
+  def self.get_derived_styles_router_for_border_shorthands(property, types, related)
+    styles = ::Archetype::Hash.new
+    types.each do |type|
+      value = get_derived_styles_router_for_border(related, "#{property}-#{type}")
+      if value
+        styles[type.to_sym] = value
+        return warn_cannot_disambiguate_property(property) if value.to_a.to_a.length > 1
+      end
+    end
+    return nil if styles.empty?
+    return Sass::Script::Value::List.new(extrapolate_shorthand_simple(styles, property, types), :space)
+  end
+
+  #
+  # router for `border` properties
+  #
+  def self.get_derived_styles_router_for_border(related, property)
+    properties = {
+      :image  => %w(image-source image-slice image-width image-outset image-repeat),
+      :radius => %w(top-left-radius top-right-radius bottom-right-radius bottom-left-radius)
+    }
+    positions = %w(top right bottom left)
+    types = %w(width style color)
+
+    # shorthand for `border` and `border-{position}` will extrapolate from other shorthands
+    return get_derived_styles_router_for_border_shorthands(property, types, related) if property =~ R_BORDER_SHORTHANDS
+
+    case_type = case property
+    when R_BORDER_IMG_OR_RADIUS
+      $1.to_sym
+    when R_BORDER_STD
+      :border
+    end
+
+    properties = properties[case_type] || []
+    styles = ::Archetype::Hash.new
+    augmented = false
+
+    with_each_available_relative(related, property) do |key, value|
+      items = value.to_a.dup
+
+      case case_type
+      when :image
+        # border-image
+        styles[normalize_property_key(key)] = value
+        augmented = !is_root_property?(key)
+        if !augmented
+          styles = deconstruct_shorthand_for_border_image(items, properties)
+        end
+      when :radius
+        # border-radius
+        pieces = key.split('-')
+        if pieces.length > 2
+          augmented = true
+          if pieces.length > 3
+            # one of the longhand properties
+            # e.g. `border-top-right-radius`
+            styles[normalize_property_key(key)] = value
+          else
+            # one of the not-so-short shorthands
+            # e.g. `border-top-radius` (these aren't real properties, but Compass supports these, so why not)
+            position = pieces[1]
+            positions = [
+              ['top', 'bottom'],
+              ['left', 'right']
+            ]
+            vertical = positions[0].include?(position)
+            positions[vertical ? 1 : 0].each do |alt_position|
+              str = "border-#{vertical ? position : alt_position}-#{vertical ? alt_position : position}-radius"
+              styles[normalize_property_key(str)] = value
+            end
+          end
+        else
+          augmented = false
+          shorthand = items.to_a
+          # TODO - doesn't support vertical radius correctly
+          styles = ::Archetype::Hash.new
+          styles[:top_left_radius]      = shorthand[0],
+          styles[:top_right_radius]     = shorthand[1] || shorthand[0],
+          styles[:bottom_right_radius]  = shorthand[2] || shorthand[0],
+          styles[:bottom_left_radius]   = shorthand[3] || shorthand[1] || shorthand[0]
+        end
+      when :border
+        key =~ R_BORDER_STD
+        position, type = $1, $2
+        if position or type
+          augmented = true
+          if position and type
+            # one of the longhand properties
+            # e.g. `border-top-style`
+            styles[normalize_property_key(key)] = value
+          else
+            # one of the not-so-short shorthands
+            # e.g. `border-top` or `border-style`
+            if position
+              # e.g. `border-top`
+              tmp = deconstruct_shorthand_for_border(items, types)
+              types.each { |k| styles[normalize_property_key("#{key}-#{k}")] = tmp[k.to_sym] }
+            else
+              # e.g. `border-style`
+              pattern = /^border#{RS_BORDER_POSITION}#{type}$/
+              tmp = extract_symmetical_values(items)
+              ALL_CSS_PROPERTIES.each { |k, v| styles[normalize_property_key(k)] = tmp[$1.gsub('-', '').to_sym] if k =~ pattern }
+            end
+          end
+        else
+          tmp = deconstruct_shorthand_for_border(items, types)
+          positions.each do |pos|
+            types.each { |k| styles[normalize_property_key("border-#{pos}-#{k}")] = tmp[k.to_sym] }
+          end
+        end
+      end
+    end
+    pattern = /^border#{RS_BORDER_TYPE}$/
+
+    styles = collapse_multi_value_lists(styles)
+
+    if (augmented and is_root_property?(property)) or property =~ pattern
+      value = nil
+      case case_type
+      when :image
+        slash = Sass::Script::Value::String.new('/')
+        styles = set_default_styles(styles, 'border-image', properties)
+        value = [styles[:image_source], styles[:image_slice], slash, styles[:image_width], slash, styles[:image_outset], styles[:image_repeat]]
+      when :border
+        # e.g. border-color
+        type = $1
+        tmp = ::Archetype::Hash.new
+        positions.each do |pos|
+          key = "border-#{pos}#{type}"
+          tmp[pos.to_sym] = styles[normalize_property_key(key)] || default(key)
+        end
+        return nil if tmp.empty?
+        return extrapolate_shorthand_symmetrical(tmp)
+      else
+        # radius
+        value = extrapolate_shorthand_simple(styles, property, properties)
+      end
+      return value ? Sass::Script::Value::List.new(value, :space) : nil
+    end
+
+    return styles[normalize_property_key(property)]
+  end
+end