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

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

@@ -0,0 +1,40 @@
+module Archetype::SassExtensions::Styleguide
+
+  private
+
+  #
+  # keep a registry of styleguide themes
+  #
+  # *Parameters*:
+  # - <tt>theme</tt> {String} the theme to use
+  # *Returns*:
+  # - {Hash} the theme
+  #
+  def get_theme(theme)
+    if @@styleguide_themes.nil?
+      # bind a callback to file save to cleanup the cache if needed
+      Compass.configuration.on_stylesheet_saved do |filename|
+        ::Archetype::SassExtensions::Styleguide.reset!(filename) unless Compass.configuration.memoize == :aggressive
+      end
+    end
+    @@styleguide_themes ||= {}
+    theme_name = helpers.to_str(theme || environment.var('CONFIG_THEME') || Archetype.name)
+    key = nil
+    begin
+      key = environment.options[:css_filename].hash
+    end
+    # if we're aggressively memoizing, store everything across the session
+    if Compass.configuration.memoize == :aggressive or not key
+      styleguide_store = @@styleguide_themes
+    #otherwise, just store it per this file instance
+    else
+      styleguide_store = @@styleguide_themes[key] ||= {}
+    end
+    theme = styleguide_store[theme_name] ||= {}
+    theme[:name] ||= theme_name
+    theme[:components] ||= {}
+    theme[:extensions] ||= []
+    return theme
+  end
+
+end

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

@@ -1,60 +1,10 @@
-require 'archetype/functions/helpers'
-require 'thread'
+module Archetype::SassExtensions::UI; end
 
-#
-# This module provides some UI helper methods.
-#
-module Archetype::SassExtensions::UI
-  # :stopdoc:
-  @@archetype_ui_mutex = Mutex.new
-  # :startdoc:
-
-  #
-  # generate a unique token
-  #
-  # *Parameters*:
-  # - <tt>$prefix</tt> {String} a string to prefix the UID with, `class` and `id` will generate a unique selector
-  # *Returns*:
-  # - {String} the unique string
-  #
-  def unique(prefix = '')
-    prefix = helpers.to_str(prefix, ' ', :quotes)
-    prefix = '.' if prefix == 'class'
-    prefix = '#' if prefix == 'id'
-    suffix = Compass.configuration.testing ? "RANDOM_UID" : "#{Time.now.to_i}-#{rand(36**8).to_s(36)}-#{uid}"
-    return Sass::Script::String.new("#{prefix}archetype-uid-#{suffix}")
-  end
-
-  #
-  # parse a CSS content string and format it for injection into innerHTML
-  #
-  # *Parameters*:
-  # - <tt>$content</tt> {String} the CSS content string
-  # *Returns*:
-  # - {String} the processed string
-  #
-  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-zA-Z]{4})\s?/, '&#x\1;')
-    # escape tags and cleanup quotes
-    content = content.gsub(/\</, '&lt;').gsub(/\>/, '&gt;')
-    # cleanup quotes
-    content = content.gsub(/\A"|"\Z/, '').gsub(/\"/, '\\"')
-    return Sass::Script::String.new(content)
-  end
-
-private
-  def helpers
-    @helpers ||= Archetype::Functions::Helpers
-  end
+%w(glyphs scopes).each do |func|
+  require "archetype/sass_extensions/functions/ui/#{func}"
+end
 
-  def uid
-    @@archetype_ui_mutex.synchronize do
-      @@uid ||= 0
-      @@uid += 1
-    end
-  end
+module Archetype::SassExtensions::UI
+  include Archetype::SassExtensions::UI::Glyphs
+  include Archetype::SassExtensions::UI::Scopes
 end

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

@@ -0,0 +1,118 @@
+module Archetype::SassExtensions::UI::Glyphs
+
+  #
+  # given a set of grid sizes and an individual size, return the closest matching size
+  #
+  # *Parameters*:
+  # - <tt>$grids</tt> {List} the list of grid options
+  # - <tt>$size</tt> {Number} the size to find a match for
+  # *Returns*:
+  # - {Number} the closest matching grid size
+  #
+  def choose_best_glyph_grid(grids, size)
+    return grids if grids == null
+
+    grids = grids.to_a
+
+    # perfect match?
+    if grids.include?(size)
+      return size
+    end
+
+    # otherwise let's find the best match
+    # start with assuming the first item is the best
+    best = {
+      :grid     => grids.first,
+      :distance => (+1.0/0.0) # similuate Float::INFINITY, but for Ruby 1.8
+    }
+
+    # for each grid option...
+    grids.each do |grid|
+      # if the units are comparable...
+      if unit(grid) == unit(size)
+
+        tmp_grid = strip_units(grid).value.to_f
+        tmp_size = strip_units(size).value.to_f
+
+        # simple algorithm to compute the distance between the size and grid
+        #  choose the lesser of the (mod) or (grid - mod)
+        #  then divide it by grid^(number_of_grid_choices)
+        mod = (tmp_size % tmp_grid)
+        distance = [mod, tmp_grid - mod].min / tmp_grid**(grids.length)
+
+        # if it's closer (smaller distance), use it...
+        if distance < best[:distance]
+          best = {
+            :grid     => grid,
+            :distance => distance
+          }
+        end
+      end
+    end
+    # return the best match we found
+    return best[:grid]
+  end
+  Sass::Script::Functions.declare :choose_best_glyph_grid, [:grids, :size]
+
+  #
+  # checks if a string looks like it's just a composition of character codes
+  #
+  # *Parameters*:
+  # - <tt>$string</tt> {String} the string to check
+  # *Returns*:
+  # - {Boolean} whether or not the string looks like a sequence of character codes
+  #
+  def looks_like_character_code(string)
+    string = helpers.to_str(string, ' ', :quotes)
+    return bool(string =~ /^(\\([\da-fA-F]{4})\s*)+$/)
+  end
+  Sass::Script::Functions.declare :looks_like_character_code, [:string]
+
+
+  #
+  # registers a glyph library under a given key
+  #
+  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])
+      registry = registry.dup
+      registry[key] = library
+      registry = Sass::Script::Value::Map.new(registry)
+      environment.global_env.set_var('CONFIG_GLYPHS_LIBRARIES', registry)
+    end
+    return key
+  end
+
+  #
+  # gets a glyph library as registered under the given key
+  #
+  def get_glyph_library(key)
+    default_key = identifier('default')
+    default = archetype_glyphs_registry[default_key] || null
+    return default if key == default_key
+
+    library = archetype_glyphs_registry[key]
+    # if the library doesn't exist...
+    if helpers.is_null(library)
+      # notify the user
+      helpers.warn("[archetype:glyph] could not find a glyph library for `#{library}`, using default")
+      # and return the default
+      return default
+    end
+    # merge the library with the default
+    return map_merge(default, library)
+  end
+
+
+  def get_all_glyph_libraries
+    return environment.var('CONFIG_GLYPHS_LIBRARIES') || Sass::Script::Value::Map.new
+  end
+
+  private
+
+  def archetype_glyphs_registry
+    registry = environment.var('CONFIG_GLYPHS_LIBRARIES')
+    return registry.respond_to?(:to_h) ? registry.to_h : {}
+  end
+end

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

@@ -0,0 +1,96 @@
+module Archetype::SassExtensions::UI::Scopes
+
+  #
+  # registers a breakpoint
+  #
+  # *Parameters*:
+  # - <tt>$key</tt> {String} the key to register it under
+  # - <tt>$value</tt> {*} the value to register
+  # - <tt>$force</tt> {Boolean} if true, forces any new value into the registry
+  # *Returns*:
+  # - {Boolean} whether or not the value was registered
+  #
+  def register_breakpoint(key, value, force = nil)
+    # 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
+    # if there's no key registered...
+    if force || not_registered
+      # just register the value
+      breakpoints[key] = value
+    # otherwise, if the current value is different...
+    elsif breakpoints[key] != value
+      # throw a warning
+      helpers.warn("[#{Archetype.name}:breakpoint] a breakpoint for `#{key}` is already set to `#{breakpoints[key]}`, ignoring `#{value}`")
+      return bool(false)
+    end
+    environment.global_env.set_var('CONFIG_BREAKPOINTS', Sass::Script::Value::Map.new(breakpoints))
+    return bool(true)
+  end
+  Sass::Script::Functions.declare :register_breakpoint, [:key, :value]
+  Sass::Script::Functions.declare :register_breakpoint, [:key, :value, :force]
+
+  #
+  # retrieves a breakpoint
+  #
+  # *Parameters*:
+  # - <tt>$key</tt> {String} the key to lookup
+  # *Returns*:
+  # - {*} the registered breakpoint
+  #
+  def get_breakpoint(key)
+    return registered_breakpoints[key] || null
+  end
+  Sass::Script::Functions.declare :get_breakpoint, [:key]
+
+  #
+  # convert a modifier/element context to a BEM style selector
+  #
+  # *Parameters*:
+  # - <tt>$context</tt> {String} the root selector to scope to
+  # - <tt>$element</tt> {String} the element name
+  # - <tt>$modifier</tt> {String} the modifier
+  # *Returns*:
+  # - {String} the BEM formatted selector
+  #
+  def bem_selector(context = nil, element = nil, modifier = nil)
+    element_separator = environment.var('CONFIG_BEM_ELEMENT_SEPARATOR')
+    element_separator = element_separator.nil? ? '__' : element_separator.value
+
+    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
+
+    selector = context
+
+    warning = "[#{Archetype.name}:bem] the current context may produce a non-standard BEM selector for";
+
+    unless element.nil?
+      helpers.warn("#{warning} element `#{element}`: #{context}") if (context.include?(element_separator) || context.include?(modifier_separator))
+      selector = "#{selector}#{element_separator}#{element}"
+    end
+
+    unless modifier.nil?
+      helpers.warn("#{warning} modifier `#{modifier}`: #{context}") if context.include?(modifier_separator)
+      selector = "#{selector}#{modifier_separator}#{modifier}"
+    end
+
+    return identifier(selector)
+  end
+  Sass::Script::Functions.declare :bem_selector, [:context]
+  Sass::Script::Functions.declare :bem_selector, [:context, :element]
+  Sass::Script::Functions.declare :bem_selector, [:context, :modifier]
+  Sass::Script::Functions.declare :bem_selector, [:context, :element, :modifier]
+
+private
+
+  def registered_breakpoints
+    breakpoints = environment.var('CONFIG_BREAKPOINTS')
+    breakpoints.respond_to?(:to_h) ? breakpoints.to_h : {}
+  end
+
+end

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

@@ -0,0 +1,14 @@
+# :stopdoc:
+module Archetype::SassExtensions::Util; end
+
+%w(debug misc images spacing hacks).each do |func|
+  require "archetype/sass_extensions/functions/util/#{func}"
+end
+
+module Archetype::SassExtensions::Util
+  include Archetype::SassExtensions::Util::Misc
+  include Archetype::SassExtensions::Util::Images
+  include Archetype::SassExtensions::Util::Debug
+  include Archetype::SassExtensions::Util::Spacing
+  include Archetype::SassExtensions::Util::Hacks
+end

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

@@ -0,0 +1,22 @@
+module Archetype::SassExtensions::Util::Debug
+
+  #
+  # check if debug is enabled
+  #
+  # *Parameters*:
+  # - <tt>$iff</tt> {Boolean} optional override for `$CONFIG_DEBUG`
+  # *Returns*:
+  # - {Boolean} whether or not debug is enabled
+  #
+  def is_debug_enabled(iff = nil)
+    # debug is only available in DEBUG environments, so check that first
+    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
+    # otherwise, use `CONFIG_DEBUG`
+    return environment.var('CONFIG_DEBUG') || bool(false)
+  end
+  Sass::Script::Functions.declare :is_debug_enabled, [:iff]
+
+end

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

@@ -0,0 +1,44 @@
+module Archetype::SassExtensions::Util::Hacks
+
+  #
+  # parse a CSS content string and format it for injection into innerHTML
+  #
+  # *Parameters*:
+  # - <tt>$content</tt> {String} the CSS content string
+  # *Returns*:
+  # - {String} the processed string
+  #
+  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;')
+    # cleanup quotes
+    content = content.gsub(/\A"|"\Z/, '').gsub(/\"/, '\\"')
+    return identifier(content)
+  end
+
+  #
+  # given a string of styles, convert it into a map
+  #
+  # *Parameters*:
+  # - <tt>$string</tt> {String} the string to convert
+  # *Returns*:
+  # - {Map} the converted map of styles
+  #
+  def _style_string_to_map(string = '')
+    # convert to string and strip all comments
+    string = helpers.to_str(string, ' ').gsub(/\/\*(?!\*\/)*\*\//, '')
+    # then split it on each rule and for each rule break it into it's key-value pairs
+    styles = string.split(';').map do |rule|
+      k, v = rule.split(':')
+      [identifier(k), identifier(v)]
+    end
+    # then recompose the map
+    return Sass::Script::Value::Map.new(Sass::Util.to_hash(styles))
+  end
+
+end

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

@@ -0,0 +1,132 @@
+module Archetype::SassExtensions::Util::Images
+
+  #
+  # helper to determine if a sprite is already set or sprites are disabled
+  #
+  # *Parameters*:
+  # - <tt>$sprite</tt> {SpriteMap} the sprite map to check against
+  # *Returns*:
+  # - {Boolean} should the sprite be set
+  #
+  def _shouldSetSprite(sprite)
+    is_sprite = sprite.is_a?(Compass::SassExtensions::Sprites::SpriteMap)
+    should_set_sprite = !global_sprites_disabled? && !is_sprite
+    return bool(should_set_sprite)
+  end
+  Sass::Script::Functions.declare :get_collection, [:components, :min]
+
+  #
+  # check that a sprite isn't null or false
+  #
+  # *Parameters*:
+  # - <tt>$map</tt> {SpriteMap} the sprite map to check against
+  # *Returns*:
+  # - {Boolean} is the sprite set
+  #
+  def _archetype_check_sprite(map)
+    status = !(global_sprites_disabled? && (is_null(map) || !map.value))
+    return bool(status)
+  end
+  Sass::Script::Functions.declare :_archetype_check_sprite, [:map]
+
+  #
+  # wrapper for `sprite`
+  #
+  # *Parameters*:
+  # - <tt>$map</tt> {SpriteMap} the sprite map
+  # - <tt>$sprite</tt> {Sprite} the sprite name
+  # - <tt>$offset-x</tt> {Number} the horizontal offset of the sprite position
+  # - <tt>$offset-y</tt> {Number} the vertical offset of the sprite position
+  # *Returns*:
+  # - {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 sprite(map, sprite, offset_x, offset_y)
+  end
+  Sass::Script::Functions.declare :_archetype_sprite, [:map, :sprite, :offset_x, :offset_y]
+
+  #
+  # wrapper for `sprite-position`
+  #
+  # *Parameters*:
+  # - <tt>$map</tt> {SpriteMap} the sprite map
+  # - <tt>$sprite</tt> {Sprite} the sprite name
+  # - <tt>$offset-x</tt> {Number} the horizontal offset of the sprite position
+  # - <tt>$offset-y</tt> {Number} the vertical offset of the sprite position
+  # *Returns*:
+  # - {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 sprite_position(map, sprite, offset_x, offset_y)
+  end
+  Sass::Script::Functions.declare :_archetype_sprite_position, [:map, :sprite, :offset_x, :offset_y]
+
+  #
+  # wrapper for `sprite-url`
+  #
+  # *Parameters*:
+  # - <tt>$map</tt> {SpriteMap} the sprite map
+  # *Returns*:
+  # - {String} the sprite URL or `null`
+  #
+  def _archetype_sprite_url(map)
+    return null unless _archetype_check_sprite(map)
+    return sprite_url(map)
+  end
+  Sass::Script::Functions.declare :_archetype_sprite_url, [:map]
+
+  #
+  # wrapper for `sprite-file`
+  #
+  # *Parameters*:
+  # - <tt>$map</tt> {SpriteMap} the sprite map
+  # - <tt>$sprite</tt> {Sprite} the sprite name
+  # *Returns*:
+  # - {ImageFile} the image or `null`
+  #
+  def _archetype_sprite_file(map, sprite)
+    return null unless _archetype_check_sprite(map)
+    return sprite_file(map, sprite)
+  end
+  Sass::Script::Functions.declare :_archetype_sprite_file, [:map, :sprite]
+
+  #
+  # wrapper for `image-width`
+  #
+  # *Parameters*:
+  # - <tt>$image</tt> {ImageFile} the image
+  # - <tt>$sprite</tt> {Sprite} the sprite name
+  # *Returns*:
+  # - {Number} the width of the image or `null`
+  #
+  def _archetype_image_width(image)
+    return null if is_null(image).value
+    return image_width(image)
+  end
+  Sass::Script::Functions.declare :_archetype_image_width, [:image]
+
+  #
+  # wrapper for `image-height`
+  #
+  # *Parameters*:
+  # - <tt>$image</tt> {ImageFile} the image
+  # - <tt>$sprite</tt> {Sprite} the sprite name
+  # *Returns*:
+  # - {Number} the height of the image or `null`
+  #
+  def _archetype_image_height(image)
+    return null if is_null(image).value
+    return image_height(image)
+  end
+  Sass::Script::Functions.declare :_archetype_image_height, [:image]
+
+private
+
+  def global_sprites_disabled?
+    sprites_disabled = environment.var('CONFIG_DISABLE_STYLEGUIDE_SPRITES')
+    return sprites_disabled.respond_to?(:value) ? sprites_disabled.value : false
+  end
+
+end