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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 058c5fdcbd3d43e3cc2735abc2957391cc96e2c3
-  data.tar.gz: 7189fefda56c56cfeac9585dd15bcb23a8650bd1
+  metadata.gz: 0a95aac68fb3b20d1e69b5bccc2f4c1b362a3ed8
+  data.tar.gz: d731565e005114023d24051c1400eea8f1df0df0
 SHA512:
-  metadata.gz: 8b1938af856735dbb720e29c76bd4a26070d16649b930dea0fa490b299c126a12880c232e8569cfc005219d075abc9d1eb9d5d3ac653adfc97972ebc6ed2df50
-  data.tar.gz: 7ae8ed526d4bff1c47b92cc343c1b7bc6a2743f5100c652eb85d25ba97eaad47139ecc1783e1e830c8aaea6642290ae83dc55342a93b6a7f0c4a21ddc5d74ebb
+  metadata.gz: 31d09ec8ee79bda6aaaecbfc642ad353bfebf4f5dda1123e26344733059155c83c37bf12618b6ab3881d940ef4d4b569443e9e9972db4c647545b88955cd5c65
+  data.tar.gz: 77fcf48a05921770ff38350fa3d43f0600e0e65c2fe2fd5e05f7bed6d35e468b3468db89b8218ead71556c8cadc655de995bed42cba5810bc7d166df970b50b7

data/CHANGELOG.md

@@ -1,11 +1,75 @@
 # Changelog
 
+## 1.0.0.alpha.3
+
+### Resolved Issues:
+
+- allow `target-browser` to be called recursively, kinda
+- Sass 3.4 compatibility
+
+### New Features:
+
+- added some additional helper methods for working with styleguide components:
+  - `styleguide-remove-component`
+  - `styleguide-freeze-component` / `styleguide-thaw-component`
+  - `styleguide-freeze-all-components` / `styleguide-thaw-all-components`
+- added `styleguide-components` to retrieve a list of currently registered components
+- added `styleguide-component-variants` to retrieve a list of variants on a given component
+- added `-styleguide-grammar` method for accessing the grammar used by styleguide
+- allow special properties (with a `:`) in component definitions
+  - this allows multiple values per property, but also allows us to modify specific keys within variants / extensions without clobbering
+```
+(
+  default: (
+    'target-browser:color': (ie lte 8, color, red),
+    'target-browser:width': (ie lte 9, width, 120px),
+    color:                red,
+    'color:1':            green,
+    'color:2':            blue,
+    'color:custom':       #abc123
+  ),
+  variant: (
+    color: pink,
+    'color:custom':         #987fed,
+    'target-browser:width': nil  // we only want to modify the target-browser that's dealing with `width`, not the one for `color`
+  )
+)
+```
+- added `styleguide_debug` config option. when `true`, `styleguide*` methods will log debug information
+  - granular options include:
+    - `:get`, `:get_granular`, `:diff`, `:add`, `:extend`, `:remove`, `:freeze`, `:grammar`, `:drop`, `:inherit`, `:resolve`, `:extract`
+    - e.g. `styleguide_debug = [:add, :get, :grammar]`
+- the `styleguide` mixin can now be called recursively, preserving the context correctly
+```
+// e.g. instead of doing this...
+.container {
+  @include styleguide(container);
+  h1 {
+    @include styleguide(headline in a container);
+  }
+}
+// you can simply do...
+.container {
+  @include styleguide(container) {
+    h1 {
+      @include styleguide(headline);
+    }
+  }
+}
+```
+- added support for custom dynamic function calls from within styleguide component (the function should return a map)
+
+### Major Changes:
+
+- removed `archetype-version` in favor of `feature-exists`, `variable-exists`, `function-exists`, and `mixin-exists`
+- the `within` context keyword now matches all parent contexts (use `within` for global scope contexts, use `in` for local scope contexts -- direct parent)
+
 ## 1.0.0.alpha.2 (3/24/2014)
 
 ### Resolved Issues:
 
 - fixed broken gems
-- fix the `to-styles` to correctly apply overrides passed in via a content block when using smart content
+- fixed `to-styles` to correctly apply overrides passed in via a content block when using smart content
 
 ## 1.0.0.alpha.1 (3/24/2014)
 
@@ -13,8 +77,8 @@
 
 - support Sass 3.3.0 and Compass 1.0.0
 - `content` is no longer improperly quoted if not needed
-- fix for IE7 `:before` glyphs not being positioned correctly
-- fix for IE7 potentially crashing with `Operation Aborted` due to glyph injection
+- fixed IE7 `:before` glyphs not being positioned correctly
+- fixed IE7 potentially crashing with `Operation Aborted` due to glyph injection
 
 ### New Features:
 

data/README.md

@@ -4,7 +4,7 @@
 [![Dependency Status](https://gemnasium.com/eoneill/archetype.svg)](https://gemnasium.com/eoneill/archetype)
 
 Archetype is a Compass/Sass based framework for authoring configurable, composable UI components and patterns.
-The natural language syntax that Archetype provides allows your designers and developers to discuss UI compositions using the same vocabulary.
+The natural language syntax that Archetype provides allows designers and developer to discuss UI compositions using the same vocabulary.
 
 ## Resources
 

data/VERSION

@@ -1 +1 @@
-1.0.0.alpha.2
+1.0.0.alpha.3

data/lib/archetype.rb

@@ -38,6 +38,10 @@ module Archetype
     Compass::Configuration.add_configuration_property(:archetype_meta, "any meta data you want made available to the environment") do
       {}
     end
+    # meta
+    Compass::Configuration.add_configuration_property(:styleguide_debug, "if true, detailed debugging is turned on for styleguide components") do
+      false
+    end
   end
 
   def self.name

data/lib/archetype/actions/migrate.rb

@@ -2,6 +2,16 @@ description = "Check a set of files for migration and back-compat issues"
 if @description.nil?
   DELIMITER = "\n  "
   DATA = {
+    '1.0.0.alpha.3' => {
+      :tests => {
+        :sacss => [
+          {
+            :pattern => /(archetype[_-]version)/m,
+            :message => 'function `$1` has been removed'
+          }
+        ]
+      }
+    },
     '1.0.0.alpha.1' => {
       :notice => %q{Archetype now requires Sass 3.3+ and Compass 0.13+},
       :tests => {

data/lib/archetype/extensions.rb

@@ -10,9 +10,13 @@ module Archetype
 
       ROOT_PATH = File.expand_path("../../../", __FILE__)
 
-      def initialize(name)
+      def initialize(name, gemspec = nil, add_dependency = true)
+
+        @gemspec = gemspec
+        @add_dependency = add_dependency
 
         e = @extension = {}
+
         # we only care about the name, so strip off anything if we were given a file/path
         e[:name] = File.basename(name, '.gemspec').strip
         # the path to the extension
@@ -21,6 +25,10 @@ module Archetype
         e[:lib]  = File.join(e[:path], 'lib')
 
         resolve_version
+
+        extend_gemspec
+
+        return @gemspec
       end
 
       def info(prop)
@@ -29,6 +37,32 @@ module Archetype
 
       private
 
+      def extend_gemspec()
+        unless @gemspec.nil?
+          ## Release Specific Information
+          @gemspec.version     = info(:version)
+
+          ## most of these are just inheriting from the main archetype.gemspec
+          @gemspec.name        = info(:name)
+          @gemspec.authors     = info(:authors)
+          @gemspec.email       = info(:email)
+          @gemspec.homepage    = File.join(info(:homepage), 'extensions', info(:name))
+          @gemspec.license     = info(:license)
+
+          ## Paths
+          @gemspec.require_paths = %w(lib)
+
+          # Gem Files
+          # by default, include everything but the gemspec
+          @gemspec.files = Dir.glob("**/*") - Dir.glob("**/*.gemspec")
+
+          if @add_dependency
+            # dependencies
+            @gemspec.add_dependency('archetype', "~> #{Archetype::VERSION}") # assume a dependency on the latest current version of Archetype
+          end
+        end
+      end
+
       def resolve_version
         # if a version.rb file exists within the extension, we'll get the version from that
         version_rb = File.join(@extension[:lib], @extension[:name], 'version.rb')

data/lib/archetype/functions/helpers.rb

@@ -29,6 +29,14 @@ module Archetype::Functions::Helpers
     logger.record(:warning, msg)
   end
 
+  #
+  # provides a convenience interface for logging debug messages
+  # silently captures failures
+  #
+  def self.debug(msg)
+    logger.record(:debug, msg)
+  end
+
   #
   # convert an Archetype::Hash to a Sass::Script::Value::List
   #

data/lib/archetype/functions/styleguide_memoizer.rb

@@ -20,7 +20,7 @@ private
   #
   def self.tokenize(theme, extensions, id, modifiers, state)
     return nil if extensions.nil? or id.nil?
-    return "#{id}::#{(modifiers.to_a.sort + extensions).join('$')}::#{state}".hash
+    return "#{id}::#{(modifiers.to_a.sort + extensions).join('$')}::#{state}"
   end
 
   #

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

@@ -22,7 +22,7 @@ module Archetype::SassExtensions::Environment
   #
   def archetype_namespace(string)
     namespace = environment.var('CONFIG_NAMESPACE')
-    return string if is_null(namespace).value
+    return string if helpers.is_null(namespace)
     return identifier(namespace.value + '_' + string.value)
   end
 

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

@@ -15,7 +15,7 @@ module Archetype::SassExtensions::Lists
   #
   def list_replace(list, idx = false, value = nil, separator = nil)
     # return early if the index is invalid (no operation)
-    return list if (!idx || is_null(idx).value || idx.value == false)
+    return list if (!idx || helpers.is_null(idx) || idx.value == false)
     separator ||= list.separator if list.is_a?(Sass::Script::Value::List)
     # cast and zero-index $idx
     idx = (idx.value) - 1
@@ -188,6 +188,7 @@ module Archetype::SassExtensions::Lists
   # - {*} the nth item in the List
   #
   def nth_cyclic(list, n = 1)
+    n = 1 if helpers.is_null(n)
     n = n.to_i if n.is_a?(Sass::Script::Value::Number)
     list = list.to_a
     return list[(n - 1) % list.size]

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

@@ -11,91 +11,6 @@ end
 #
 module Archetype::SassExtensions::Styleguide
 
-  #
-  # interface for adding new components to the styleguide structure
-  #
-  # *Parameters*:
-  # - <tt>$id</tt> {String} the component identifier
-  # - <tt>$data</tt> {Map|List} the component data object
-  # - <tt>$default</tt> {Map|List} the default data object (for extending)
-  # - <tt>$theme</tt> {String} the theme to insert the component into
-  # - <tt>$force</tt> {Boolean} if true, forcibly insert the component
-  # *Returns*:
-  # - {Boolean} whether or not the component was added
-  #
-  def styleguide_add_component(id, data, default = nil, theme = nil, force = false)
-    @@archetype_styleguide_mutex.synchronize do
-      theme = get_theme(theme)
-      components = theme[:components]
-      id = helpers.to_str(id)
-      # if force was true, we have to invalidate the memoizer
-      memoizer.clear(theme[:name]) if force
-      # if we already have the component, don't create it again
-      return Sass::Script::Bool.new(false) if component_exists(id, theme, nil, force)
-      # otherwise add it
-      components[id] = helpers.data_to_hash(default, 1, SPECIAL, ADDITIVES).merge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
-      return Sass::Script::Bool.new(true)
-    end
-  end
-  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data]
-  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data, :default]
-  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data, :default, :theme]
-
-  #
-  # interface for extending an existing components in the styleguide structure
-  #
-  # *Parameters*:
-  # - <tt>$id</tt> {String} the component identifier
-  # - <tt>$data</tt> {List} the component data object
-  # - <tt>$theme</tt> {String} the theme to insert the component into
-  # - <tt>$extension</tt> {String} the name of the extension
-  # - <tt>$force</tt> {Boolean} if true, forcibly extend the component
-  # *Returns*:
-  # - {Boolean} whether or not the component was extended
-  #
-  def styleguide_extend_component(id, data, theme = nil, extension = nil, force = false)
-    @@archetype_styleguide_mutex.synchronize do
-      theme = get_theme(theme)
-      components = theme[:components]
-      id = helpers.to_str(id)
-      # if force was set, we'll create a random token for the name
-      extension = rand(36**8).to_s(36) if force
-      # convert the extension into a hash (if we don't have an extension, compose one out of its data)
-      extension = helpers.to_str(extension || data).hash
-      extensions = theme[:extensions]
-      return Sass::Script::Bool.new(false) if component_exists(id, theme, extension, force)
-      extensions.push(extension)
-      components[id] = (components[id] ||= Archetype::Hash.new).rmerge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
-      return Sass::Script::Bool.new(true)
-    end
-  end
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data]
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data, :theme]
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data, :theme, :extension]
-
-  #
-  # check whether or not a component (or a component extension) has already been defined
-  #
-  # *Parameters*:
-  # - <tt>$id</tt> {String} the component identifier
-  # - <tt>$data</tt> {List} the component data object
-  # - <tt>$theme</tt> {String} the theme to insert the component into
-  # - <tt>$extension</tt> {String} the name of the extension
-  # - <tt>$force</tt> {Boolean} if true, forcibly extend the component
-  # *Returns*:
-  # - {Boolean} whether or not the component/extension exists
-  #
-  def styleguide_component_exists(id, theme = nil, extension = nil, force = false)
-    @@archetype_styleguide_mutex.synchronize do
-      extension = helpers.to_str(extension).hash if not extension.nil?
-      return Sass::Script::Bool.new( component_exists(id, theme, extension, force) )
-    end
-  end
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id]
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :theme]
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :theme, :extension]
-  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :theme, :extension, :force]
-
   #
   # given a description of the component, convert it into CSS
   #
@@ -106,9 +21,18 @@ module Archetype::SassExtensions::Styleguide
   # - {Map} a map of styles
   #
   def _styleguide(description, state = nil, theme = nil)
-    @@archetype_styleguide_mutex.synchronize do
+    extras = []
+    extras << "state: #{state}" unless (state.nil? or helpers.is_null(state))
+    extras << "theme: #{theme}" unless (theme.nil? or helpers.is_null(theme))
+    extras = extras.join(', ')
+    msg = "`#{description}`"
+    msg << " (#{extras})" unless extras.empty?
+    _styleguide_debug "fetching styles for #{msg}", :get
+    _styleguide_mutex_helper do
       styles = get_styles(description, theme, state)
       styles = resolve_runtime_locale_values(styles)
+      _styleguide_debug "got styles for #{msg}", :get
+      _styleguide_debug styles, :get
       # convert it back to a Sass:Map and carry on
       return helpers.hash_to_map(styles)
     end
@@ -124,7 +48,7 @@ module Archetype::SassExtensions::Styleguide
   # - {List} a key-value paired list of styles
   #
   def styleguide_diff(original, other)
-    @@archetype_styleguide_mutex.synchronize do
+    _styleguide_mutex_helper do
       # normalize our input (for back-compat)
       original = normalize_styleguide_definition(original)
       other = normalize_styleguide_definition(other)
@@ -134,6 +58,8 @@ module Archetype::SassExtensions::Styleguide
       original_message = helpers.get_meta_message(original).sub(MESSAGE_PREFIX, '').sub(MESSAGE_SUFFIX, '')
       other_message = helpers.get_meta_message(other).sub(MESSAGE_PREFIX, '').sub(MESSAGE_SUFFIX, '')
       diff = helpers.add_meta_message(diff, "#{MESSAGE_PREFIX}#{original_message}` vs `#{other_message}#{MESSAGE_SUFFIX}")
+      _styleguide_debug "styleguide-diff", :diff
+      _styleguide_debug diff, :diff
       # and return it as a map
       return helpers.hash_to_map(diff)
     end
@@ -151,7 +77,7 @@ module Archetype::SassExtensions::Styleguide
   # - {List|Map|*} either a list/map of the values or the individual value itself
   #
   def styleguide_derived_style(definition, properties = [], format = 'auto', strict = false)
-    @@archetype_styleguide_mutex.synchronize do
+    _styleguide_mutex_helper do
       # normalize our input
       definition = normalize_styleguide_definition(definition)
       # get the computed styles
@@ -159,4 +85,35 @@ module Archetype::SassExtensions::Styleguide
     end
   end
 
+  #
+  # updates the global styleguide context stack
+  #
+  # *Parameters*:
+  # - <tt>$definition</tt> {List} the description of the component, if not passed, removes the last item from the stack
+  #
+  def _styleguide_shift_context(definition = nil)
+    # get the current stack...
+    stack = styleguide_stack()
+    # if we have a definition to push onto it, do so...
+    if definition
+      stack << definition
+    # otherwise pop the last item off
+    else
+      stack.pop
+    end
+    # and update the stack
+    styleguide_stack(stack)
+    return bool(true)
+  end
+
+  private
+
+  def styleguide_stack(stack = nil)
+    if stack.nil?
+      return (environment.var('ARCHETYPE_STYLEGUIDE_STACK') || []).to_a.dup
+    else
+      environment.global_env.set_var('ARCHETYPE_STYLEGUIDE_STACK', list(stack, :comma))
+    end
+  end
+
 end

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

@@ -1,7 +1,236 @@
 module Archetype::SassExtensions::Styleguide
+  #
+  # interface for adding new components to the styleguide structure
+  #
+  # *Parameters*:
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$data</tt> {Map|List} the component data object
+  # - <tt>$default</tt> {Map|List} the default data object (for extending)
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  # - <tt>$force</tt> {Boolean} if true, forcibly insert the component
+  # *Returns*:
+  # - {Boolean} whether or not the component was added
+  #
+  def styleguide_add_component(id, data, default = nil, theme = nil, force = false)
+    _styleguide_debug "attempting to register component for `#{id}`", :add
+    _styleguide_mutex_helper(id, theme) do |id, theme|
+      components = theme[:components]
+      # if force was true, we have to invalidate the memoizer
+      memoizer.clear(theme[:name]) if force
+      # if we already have the component, don't create it again
+      if component_exists?(id, theme, nil, force) || component_is_frozen?(id, theme)
+        _styleguide_debug "skipping component registration for `#{id}`. the component is already registered or frozen", :add
+        return bool(false)
+      end
+      # otherwise add it
+      components[id] = helpers.data_to_hash(default, 1, SPECIAL, ADDITIVES).merge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
+      _styleguide_debug "successfully registered component `#{id}`", :add
+      _styleguide_debug components[id], :add
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data]
+  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data, :default]
+  Sass::Script::Functions.declare :styleguide_add_component, [:id, :data, :default, :theme]
+
+  #
+  # interface for extending an existing components in the styleguide structure
+  #
+  # *Parameters*:
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$data</tt> {List} the component data object
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  # - <tt>$extension</tt> {String} the name of the extension
+  # - <tt>$force</tt> {Boolean} if true, forcibly extend the component
+  # *Returns*:
+  # - {Boolean} whether or not the component was extended
+  #
+  def styleguide_extend_component(id, data, theme = nil, extension = nil, force = false)
+    _styleguide_debug "attempting to extend component for `#{id}`", :extend
+    _styleguide_debug "extension name is `#{extension.to_sass}`", :extend unless extension.nil?
+    _styleguide_mutex_helper(id, theme) do |id, theme|
+      components = theme[:components]
+      # if force was set, we'll create a random token for the name
+      if force
+        extension = random_uid('extension')
+        _styleguide_debug "forcibly extending...", :extend
+      end
+      # use the extension name or a snapshot of the extension
+      extension = helpers.to_str(extension || data.to_sass)
+      extensions = theme[:extensions]
+      if component_exists?(id, theme, extension, force) || component_is_frozen?(id, theme)
+        _styleguide_debug "skipping component extension for `#{id}`. the extension is already registered or frozen", :extend
+        return bool(false)
+      end
+      extensions.push(extension)
+      components[id] = (components[id] ||= Archetype::Hash.new).rmerge(helpers.data_to_hash(data, 1, SPECIAL, ADDITIVES))
+      _styleguide_debug "successfully extended component `#{id}`", :extend
+      _styleguide_debug components[id], :extend
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data]
+  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data, :theme]
+  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data, :extension]
+  Sass::Script::Functions.declare :styleguide_extend_component, [:id, :data, :theme, :extension]
+
+  #
+  # check whether or not a component (or a component extension) has already been defined
+  #
+  # *Parameters*:
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$data</tt> {List} the component data object
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  # - <tt>$extension</tt> {String} the name of the extension
+  # - <tt>$force</tt> {Boolean} if true, forcibly extend the component
+  # *Returns*:
+  # - {Boolean} whether or not the component/extension exists
+  #
+  def styleguide_component_exists(id, theme = nil, extension = nil, force = false)
+    _styleguide_mutex_helper do
+      extension = helpers.to_str(extension) if not extension.nil?
+      return bool( component_exists?(id, theme, extension, force) )
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_component_exists, [:id]
+  Sass::Script::Functions.declare :styleguide_component_exists, [:id, :theme]
+  Sass::Script::Functions.declare :styleguide_component_exists, [:id, :theme, :extension]
+  Sass::Script::Functions.declare :styleguide_component_exists, [:id, :theme, :extension, :force]
+
+  #
+  # removes a component definition
+  #
+  # *Parameters*
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  #
+  def styleguide_remove_component(id, theme = nil)
+    _styleguide_debug "removing component `#{id}`", :remove
+    _styleguide_mutex_helper(id, theme) do |id, theme|
+      theme[:components].delete(id)
+      theme[:extensions].push(random_uid('remove'))
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_remove_component, [:id]
+  Sass::Script::Functions.declare :styleguide_remove_component, [:id, :theme]
+
+  #
+  # flags a component definition as "frozen" (locked)
+  #
+  # *Parameters*
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  #
+  def styleguide_freeze_component(id, theme = nil)
+    _styleguide_debug "freezing component `#{id}`", :freeze
+    _styleguide_mutex_helper(id, theme) do |id, theme|
+      theme[:frozen] << id
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_freeze_component, [:id]
+  Sass::Script::Functions.declare :styleguide_freeze_component, [:id, :theme]
+
+  #
+  # freezes all registered components
+  #
+  # *Parameters*
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  #
+  def styleguide_freeze_all_components(theme = nil)
+    _styleguide_debug "freezing ALL components", :freeze
+    _styleguide_mutex_helper do
+      theme = get_theme(theme)
+      theme[:frozen] = Set.new(theme[:components].keys)
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_freeze_all_components, [:theme]
+
+  #
+  # "thaws" (unlocks) a frozen component
+  #
+  # *Parameters*
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  #
+  def styleguide_thaw_component(id, theme = nil)
+    _styleguide_debug "thawing component `#{id}`", :freeze
+    _styleguide_mutex_helper(id, theme) do |id, theme|
+      theme[:frozen].delete(id)
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_thaw_component, [:id]
+  Sass::Script::Functions.declare :styleguide_thaw_component, [:id, :theme]
+
+  #
+  # freezes all registered components
+  #
+  # *Parameters*
+  # - <tt>$theme</tt> {String} the theme to insert the component into
+  #
+  def styleguide_thaw_all_components(theme = nil)
+    _styleguide_debug "thawing ALL components", :freeze
+    _styleguide_mutex_helper do
+      theme = get_theme(theme)
+      theme[:frozen].clear
+      return bool(true)
+    end
+  end
+  Sass::Script::Functions.declare :styleguide_thaw_all_components, [:theme]
+
+  #
+  # gets a list of all known components
+  #
+  # *Parameters*:
+  # - <tt>$theme</tt> {String} the theme to look within
+  # *Returns*:
+  # - {List} list of component identifiers
+  #
+  def styleguide_components(theme = nil)
+    theme = get_theme(theme)
+    keys = theme[:components].keys.map { |k| identifier(k) }
+    return list(keys, :comma)
+  end
+
+  #
+  # gets a list of all the current variants of a given component
+  #
+  # *Parameters*:
+  # - <tt>$id</tt> {String} the component identifier
+  # - <tt>$theme</tt> {String} the theme to look within
+  # *Returns*:
+  # - {List} list of component variants
+  #
+  def styleguide_component_variants(id, theme = nil)
+    id = helpers.to_str(id)
+    theme = get_theme(theme)
+    component = theme[:components][id]
+    return null if component.nil?
+    variants = component.keys
+    variants = variants.map { |k| identifier(k) }
+    return list(variants, :comma)
+  end
 
   private
 
+  #
+  # TODO - doc
+  #
+  def random_uid(str = '')
+    return rand(36**8).to_s(36) + str
+  end
+
+  def component_is_frozen?(id, theme, warn = true)
+    if theme[:frozen].include?(id)
+      helpers.warn "[#{Archetype.name}:styleguide:frozen] the component `#{id}` has been frozen and cannot be modified" if warn
+      return true
+    end
+    return false
+  end
+
   #
   # check whether or not a component (or a component extension) has already been defined
   #
@@ -13,7 +242,7 @@ module Archetype::SassExtensions::Styleguide
   # *Returns*:
   # - {Boolean} whether or not the component/extension exists
   #
-  def component_exists(id, theme = nil, extension = nil, force = false)
+  def component_exists?(id, theme = nil, extension = nil, force = false)
     status = false
     theme = get_theme(theme) if not theme.is_a? Hash
     id = helpers.to_str(id)