archetype 1.0.0.alpha.2 → 1.0.0.alpha.3

data/lib/archetype/sass_extensions/functions/styleguide/constants.rb

@@ -20,7 +20,6 @@ module Archetype::SassExtensions::Styleguide
   MULTIMIXINS = %w(target-browser)
   # NOTE: these are no longer used/needed if you're using the map structures
   ADDITIVES   = FALLBACKS + [DROP, INHERIT, STYLEGUIDE] + MULTIMIXINS
-  @@archetype_styleguide_mutex = Mutex.new
   @@styleguide_themes ||= nil
   # :startdoc:
 

data/lib/archetype/sass_extensions/functions/styleguide/grammar.rb

@@ -1,5 +1,35 @@
 module Archetype::SassExtensions::Styleguide
 
+  #
+  # exposes the grammar used when interpreting styleguide calls
+  #
+  # *Parameters*:
+  # - <tt>sentence</tt> {String|List} the sentence describing the component
+  # - <tt>theme</tt> {String} the theme to use
+  # - <tt>state</tt> {String} the name of a state to return
+  # *Returns*:
+  # - {Map} a map including the `identifier` and `modifiers`
+  def _styleguide_grammar(sentence, theme = nil, state = nil)
+    keys = ['identifier', 'modifiers', 'token']
+    id, modifiers, token = grammar(sentence, theme, state)
+
+    # if the id is empty, then it means that the sentence didn't contain a valid component id
+    # so we set everything to `null`
+    unless id
+      id = null
+      modifiers = null
+    # otherwise we ensure that we're sending back appropriate values
+    else
+      id = identifier(id)
+      modifiers = modifiers.empty? ? null : list(modifiers.map{|m| identifier(m)}, :space)
+    end
+
+    return Sass::Script::Value::Map.new({
+      identifier('identifier') => id,
+      identifier('modifiers') => modifiers
+    });
+  end
+
   private
 
   #
@@ -13,11 +43,28 @@ module Archetype::SassExtensions::Styleguide
   # - {Array} an array containing the identifer, modifiers, and a token
   #
   def grammar(sentence, theme = nil, state = nil)
+    _styleguide_debug "converting `#{sentence}` to grammar", :grammar
     theme = get_theme(theme)
     components = theme[:components]
     # get a list of valid ids
     styleguideIds = components.keys
-    sentence = sentence.split if sentence.is_a? String
+
+    # convert the sentence to a string and then split into an array
+    # this ensures that all the pieces are treated as strings and not other primitive types (e.g. a list of strings in the middle of a sentence)
+    sentence = helpers.to_str(sentence).split
+
+    # update the sentence to be aware of it's current styleguide context
+    withins = []
+    styleguide_stack.reverse_each do |context|
+      sentence << 'in'
+      context = context.to_a
+      sentence.concat(context)
+      withins.concat(context)
+    end
+    unless withins.empty?
+      sentence << 'within'
+      sentence.concat(withins)
+    end
 
     id, modifiers = grammarize(sentence, styleguideIds)
 
@@ -30,6 +77,13 @@ module Archetype::SassExtensions::Styleguide
     # maybe in the case where we're looking for strict keys on the lookup?
     modifiers = modifiers.uniq
     token = memoizer.tokenize(theme[:name], extensions, id, modifiers, state)
+    if id
+      _styleguide_debug "the computed grammar is...", :grammar
+      _styleguide_debug "  identifier: #{id}", :grammar
+      unless modifiers.empty?
+        _styleguide_debug "  modifiers: #{modifiers.join(', ')}", :grammar
+      end
+    end
     return id, modifiers, token
   end
 
@@ -46,7 +100,7 @@ module Archetype::SassExtensions::Styleguide
     sentence = sentence.to_a
     id = nil
     modifiers = []
-    if not sentence.empty?
+    unless sentence.empty?
       prefix = ''
       order = ''
       # these define various attributes for modifiers (e.g. `button with a shadow`)
@@ -54,16 +108,23 @@ module Archetype::SassExtensions::Styleguide
       # these are things that are useless to us, so we just leave them out
       ignore = %w(a an also the this that is was it)
       # these are our context switches (e.g. `headline in a button`)
-      contexts = %w(in within)
+      local_contexts = %w(in)
+      # these are the contexts that match all surrounding items
+      global_contexts = %w(within)
+
       sentence.each do |item|
         item = item.value if not item.is_a?(String)
         # find the ID
         if id.nil? and ids.include?(item) and prefix.empty? and order.empty?
           id = item
-        # if it's a `context`, we need to increase the depth and reset the prefix
-        elsif contexts.include?(item)
+        # if it's a `local context`, we need to increase the depth and reset the prefix
+        elsif local_contexts.include?(item)
           order = "#{item}-#{order}"
           prefix = ''
+        # if it's a `global context`, we need to reset the order, but also update the prefix
+        elsif global_contexts.include?(item)
+          order = ''#"#{item}-"
+          prefix = "#{item}-"
         # if it's an `extra`, we update the prefix
         elsif extras.include?(item)
           prefix = "#{item}-"

data/lib/archetype/sass_extensions/functions/styleguide/helpers.rb

@@ -6,6 +6,41 @@ module Archetype::SassExtensions::Styleguide
     Archetype::Functions::StyleguideMemoizer
   end
 
+  #
+  # ouputs a debug message for styleguide / component methods
+  #
+  # valid types...
+  #  :get, :get_granular, :diff, :add, :extend, :remove, :freeze, :grammar, :drop, :inherit, :resolve, :extract
+  #
+  def _styleguide_debug(msg, type = :all)
+    debug = Compass.configuration.styleguide_debug
+    debug = :all if debug == true
+    debug = [debug] unless debug.is_a? Array
+    if debug.include?(type) || debug.include?(:all)
+      begin
+        if msg.is_a? String
+          helpers.debug("[archetype:styleguide] #{msg}")
+        else
+          puts ">" * 50
+          pp msg
+          puts "<" * 50
+        end
+      rescue
+      end
+    end
+  end
+
+  #
+  # helper for operations that need to happen within a mutex
+  #
+  def _styleguide_mutex_helper(id = nil, theme = nil)
+    (@@archetype_styleguide_mutex ||= Mutex.new).synchronize do
+      if block_given?
+        id.nil? ? yield : yield(helpers.to_str(id), get_theme(theme))
+      end
+    end
+  end
+
   #
   # normalize the styleguide definition into a hash representative of the definition
   #
@@ -24,7 +59,7 @@ module Archetype::SassExtensions::Styleguide
   end
 
   def self.reset!(filename = nil)
-    @@archetype_styleguide_mutex.synchronize do
+    (@@archetype_styleguide_mutex ||= Mutex.new).synchronize do
       if filename.nil?
         @@styleguide_themes = {}
       else

data/lib/archetype/sass_extensions/functions/styleguide/resolve.rb

@@ -22,7 +22,10 @@ module Archetype::SassExtensions::Styleguide
     if not drop.nil?
       drop.to_a.each do |key|
         key = helpers.to_str(key)
-        obj.delete(key) if not SPECIAL.include?(key)
+        if not SPECIAL.include?(key)
+          _styleguide_debug "dropping styles for `#{key}`", :drop
+          obj.delete(key)
+        end
       end
       merger.delete(DROP)
     end
@@ -84,6 +87,7 @@ module Archetype::SassExtensions::Styleguide
   # - <tt>key</tt> {String} the key we care about
   #
   def special_drop_key(obj, tmp, key)
+    _styleguide_debug "dropping styles for `#{key}`", :drop
     if SPECIAL.include?(key)
       if not (obj[key].nil? or obj[key].empty?)
         tmp[key] = Archetype::Hash.new
@@ -108,6 +112,7 @@ module Archetype::SassExtensions::Styleguide
   #
   def resolve_dependents(id, value, theme = nil, context = nil, obj = nil)
     return value if value.nil?
+    debug = Compass.configuration.styleguide_debug
     # we have to create a clone here as the passed in value is volatile and we're performing destructive changes
     value = value.clone
     # check that we're dealing with a hash
@@ -126,7 +131,10 @@ module Archetype::SassExtensions::Styleguide
         if not inherit.empty?
           # create a temporary object and extract the nested styles
           tmp = Archetype::Hash.new
-          inherit.each { |related| tmp = tmp.rmerge(extract_styles(id, related, true, theme, context)) }
+          inherit.each do |related|
+            _styleguide_debug "inheriting from `#{helpers.to_str(related)}`", :inherit
+            tmp = tmp.rmerge(extract_styles(id, related, true, theme, context))
+          end
           # remove the inheritance key and update the styles
           value.delete(INHERIT)
           inherit = extract_styles(id, inherit, true, theme, context)
@@ -136,6 +144,8 @@ module Archetype::SassExtensions::Styleguide
       end
     end
     # return whatever we got
+    _styleguide_debug "after resolving dependents...", :resolve
+    _styleguide_debug value, :resolve
     return value
   end
 

data/lib/archetype/sass_extensions/functions/styleguide/styles.rb

@@ -24,14 +24,15 @@ module Archetype::SassExtensions::Styleguide
     out = out.clone
     return Archetype::Hash.new if out == null
     # if it's not strict, find anything that matched
-    if not strict
+    unless strict
       modifiers = modifiers.split
       context.each do |key, definition|
         modifier = grammarize(key.split(' '))[1].join(' ')
-        if modifier != DEFAULT
+        unless modifier == DEFAULT
           match = true
           modifier = modifier.split
           if modifier[0] == REGEX
+            _styleguide_debug "finding regex matches", :extract
             # if it's a regex pattern, test if it matches
             match = modifiers.join(' ') =~ /#{modifier[1].gsub(/\A"|"\Z/, '')}/i
           else
@@ -40,6 +41,7 @@ module Archetype::SassExtensions::Styleguide
           end
           # if it matched, process it
           if match
+            _styleguide_debug "`#{key}` is a matching variant", :extract
             tmp = resolve_dependents(id, definition, theme[:name], nil, out)
             out, tmp = post_resolve_drops(out, tmp)
             out = out.rmerge(tmp) if not helpers.is_value(tmp, :nil)
@@ -112,13 +114,14 @@ module Archetype::SassExtensions::Styleguide
           extracted = extract_styles(id, modifiers, false, theme)
           # we can delete anything that had a value of `nil` as we won't be outputting those
           extracted.delete_if { |k,v| helpers.is_value(v, :nil) }
+          _styleguide_debug extracted, :get_granular
           # expose the result to the block
           extracted
         end
         styles = styles.rmerge(extracted)
       elsif not helpers.is_value(sentence, :nil)
         msg = modifiers.length > 0 ? "please specify one of: #{modifiers.sort.join(', ')}" : "there are no registered components"
-        helpers.warn("[#{Archetype.name}:styleguide:missing_identifier] `#{helpers.to_str(sentence)}` does not contain an identifier. #{msg}")
+        helpers.warn("[#{Archetype.name}:styleguide:identifier] `#{helpers.to_str(sentence)}` does not contain an identifier. #{msg}")
       end
     end
 

data/lib/archetype/sass_extensions/functions/styleguide/themes.rb

@@ -21,7 +21,7 @@ module Archetype::SassExtensions::Styleguide
     theme_name = helpers.to_str(theme || environment.var('CONFIG_THEME') || Archetype.name)
     key = nil
     begin
-      key = environment.options[:css_filename].hash
+      key = environment.options[:css_filename]
     end
     # if we're aggressively memoizing, store everything across the session
     if Compass.configuration.memoize == :aggressive or not key
@@ -34,6 +34,7 @@ module Archetype::SassExtensions::Styleguide
     theme[:name] ||= theme_name
     theme[:components] ||= {}
     theme[:extensions] ||= []
+    theme[:frozen] ||= Set.new
     return theme
   end
 

data/lib/archetype/sass_extensions/functions/ui/glyphs.rb

@@ -75,7 +75,7 @@ module Archetype::SassExtensions::UI::Glyphs
   def register_glyph_library(key, library)
     registry = archetype_glyphs_registry
     # if it's already in the registry, just return the current list
-    if is_null(registry[key])
+    if helpers.is_null(registry[key])
       registry = registry.dup
       registry[key] = library
       registry = Sass::Script::Value::Map.new(registry)

data/lib/archetype/sass_extensions/functions/ui/scopes.rb

@@ -14,7 +14,7 @@ module Archetype::SassExtensions::UI::Scopes
     # we need a dup as the Hash is frozen
     breakpoints = registered_breakpoints.dup
     force = force.nil? ? false : force.value
-    not_registered = breakpoints[key].nil? || is_null(breakpoints[key]).value
+    not_registered = breakpoints[key].nil? || helpers.is_null(breakpoints[key])
     # if there's no key registered...
     if force || not_registered
       # just register the value
@@ -61,9 +61,9 @@ module Archetype::SassExtensions::UI::Scopes
     modifier_separator = environment.var('CONFIG_BEM_MODIFIER_SEPARATOR')
     modifier_separator = modifier_separator.nil? ? '--' : modifier_separator.value
 
-    context  = is_null(context).value  ? ''  : context.value
-    element  = is_null(element).value  ? nil : element.value
-    modifier = is_null(modifier).value ? nil : modifier.value
+    context  = helpers.is_null(context) ? ''  : context.value
+    element  = helpers.is_null(element) ? nil : element.value
+    modifier = helpers.is_null(modifier) ? nil : modifier.value
 
     selector = context
 

data/lib/archetype/sass_extensions/functions/util/debug.rb

@@ -13,7 +13,7 @@ module Archetype::SassExtensions::Util::Debug
     return bool(false) unless (environment.var('CONFIG_DEBUG_ENVS') || []).to_a.include?(archetype_env)
     # then check if the debug flag/override is truthy
     # if the param is non-null, then use it
-    return iff unless is_null(iff).value
+    return iff unless helpers.is_null(iff)
     # otherwise, use `CONFIG_DEBUG`
     return environment.var('CONFIG_DEBUG') || bool(false)
   end

data/lib/archetype/sass_extensions/functions/util/hacks.rb

@@ -1,7 +1,7 @@
 module Archetype::SassExtensions::Util::Hacks
 
   #
-  # parse a CSS content string and format it for injection into innerHTML
+  # parse a CSS content string and format it for injection into innerText
   #
   # *Parameters*:
   # - <tt>$content</tt> {String} the CSS content string
@@ -10,14 +10,10 @@ module Archetype::SassExtensions::Util::Hacks
   #
   def _ie_pseudo_content(content)
     content = helpers.to_str(content)
-    # escape &
-    content = content.gsub(/\&/, '&amp;')
-    # convert char codes (and remove single trailing whitespace if present) (e.g. \2079 -> &#x2079;)
-    content = content.gsub(/\\([\da-fA-F]{4})\s?/, '&#x\1;')
-    # escape tags and cleanup quotes
-    content = content.gsub(/\</, '&lt;').gsub(/\>/, '&gt;')
+    # convert char codes (e.g. `\2079` -> `\u2079`)
+    content.gsub!(/\\([\da-fA-F]{4})\s?/, ['\1'.hex].pack('U*'))
     # cleanup quotes
-    content = content.gsub(/\A"|"\Z/, '').gsub(/\"/, '\\"')
+    content.gsub!(/\A"|"\Z/, '').gsub!(/\"/, '\\"')
     return identifier(content)
   end
 

data/lib/archetype/sass_extensions/functions/util/images.rb

@@ -24,8 +24,7 @@ module Archetype::SassExtensions::Util::Images
   # - {Boolean} is the sprite set
   #
   def _archetype_check_sprite(map)
-    status = !(global_sprites_disabled? && (is_null(map) || !map.value))
-    return bool(status)
+    return bool(_is_sprite_valid(map))
   end
   Sass::Script::Functions.declare :_archetype_check_sprite, [:map]
 
@@ -41,7 +40,7 @@ module Archetype::SassExtensions::Util::Images
   # - {Sprite} the sprite object or `null`
   #
   def _archetype_sprite(map, sprite, offset_x = number(0), offset_y = number(0))
-    return null unless _archetype_check_sprite(map)
+    return null unless _is_sprite_valid(map)
     return sprite(map, sprite, offset_x, offset_y)
   end
   Sass::Script::Functions.declare :_archetype_sprite, [:map, :sprite, :offset_x, :offset_y]
@@ -58,7 +57,7 @@ module Archetype::SassExtensions::Util::Images
   # - {List} the sprite position or `null`
   #
   def _archetype_sprite_position(map, sprite, offset_x = number(0), offset_y = number(0))
-    return null unless _archetype_check_sprite(map)
+    return null unless _is_sprite_valid(map)
     return sprite_position(map, sprite, offset_x, offset_y)
   end
   Sass::Script::Functions.declare :_archetype_sprite_position, [:map, :sprite, :offset_x, :offset_y]
@@ -72,7 +71,7 @@ module Archetype::SassExtensions::Util::Images
   # - {String} the sprite URL or `null`
   #
   def _archetype_sprite_url(map)
-    return null unless _archetype_check_sprite(map)
+    return null unless _is_sprite_valid(map)
     return sprite_url(map)
   end
   Sass::Script::Functions.declare :_archetype_sprite_url, [:map]
@@ -87,7 +86,7 @@ module Archetype::SassExtensions::Util::Images
   # - {ImageFile} the image or `null`
   #
   def _archetype_sprite_file(map, sprite)
-    return null unless _archetype_check_sprite(map)
+    return null unless _is_sprite_valid(map)
     return sprite_file(map, sprite)
   end
   Sass::Script::Functions.declare :_archetype_sprite_file, [:map, :sprite]
@@ -102,7 +101,7 @@ module Archetype::SassExtensions::Util::Images
   # - {Number} the width of the image or `null`
   #
   def _archetype_image_width(image)
-    return null if is_null(image).value
+    return null if helpers.is_null(image)
     return image_width(image)
   end
   Sass::Script::Functions.declare :_archetype_image_width, [:image]
@@ -117,13 +116,17 @@ module Archetype::SassExtensions::Util::Images
   # - {Number} the height of the image or `null`
   #
   def _archetype_image_height(image)
-    return null if is_null(image).value
+    return null if helpers.is_null(image)
     return image_height(image)
   end
   Sass::Script::Functions.declare :_archetype_image_height, [:image]
 
 private
 
+  def _is_sprite_valid(map)
+    return !global_sprites_disabled? && !(helpers.is_null(map) || !map.value)
+  end
+
   def global_sprites_disabled?
     sprites_disabled = environment.var('CONFIG_DISABLE_STYLEGUIDE_SPRITES')
     return sprites_disabled.respond_to?(:value) ? sprites_disabled.value : false

data/lib/archetype/sass_extensions/functions/util/misc.rb

@@ -124,7 +124,7 @@ module Archetype::SassExtensions::Util::Misc
   def do_once(name)
     registry = do_once_registry
     # if it's already in the registry, just return `false`
-    return bool(false) if do_once_registry.include?(name)
+    return bool(false) if registry.include?(name)
     # update the registry with the identifier
     registry = list(registry.dup.push(name), :comma)
     environment.global_env.set_var('REGISTRY_DO_ONCE', registry)
@@ -202,6 +202,35 @@ module Archetype::SassExtensions::Util::Misc
     return best_match
   end
 
+  def _archetype_within_mixin(contexts)
+    stack = archetype_mixin_stack
+    contexts = contexts.is_a?(Sass::Script::Value::List) ? contexts.to_a : [contexts]
+    contexts.each do |context|
+      return bool(true) if stack.include?(context.to_s.gsub(/_/, '-').downcase )
+    end
+    return bool(false)
+  end
+
+  def _archetype_mixin_called_recursively()
+    stack = archetype_mixin_stack
+    current = stack.shift
+    return bool(stack.include?(current))
+  end
+
+  #
+  # normalizes a property
+  #
+  # *Parameters*:
+  # - <tt>$property</tt> {String} the property
+  # *Returns*:
+  # - {String} the normalized property
+  #
+  def _archetype_normalize_property(property)
+    return null if helpers.is_null(property)
+    property = helpers.to_str(property)
+    return identifier(property.gsub(/\:.*/, ''))
+  end
+
 private
 
   @@archetype_ui_mutex = Mutex.new
@@ -213,6 +242,10 @@ private
     end
   end
 
+  def archetype_mixin_stack
+    @environment.stack.frames.select {|f| f.is_mixin?}.reverse!.map! {|f| f.name.gsub(/_/, '-').downcase }
+  end
+
   def do_once_registry
     (environment.var('REGISTRY_DO_ONCE') || []).to_a
   end