luca 0.9.65 → 0.9.76

data/src/core/meta_data.coffee

@@ -0,0 +1,93 @@
+Luca.registry.componentMetaData = {}
+
+Luca.registry.getMetaDataFor = (componentName)->
+  new MetaDataProxy(Luca.registry.componentMetaData[ componentName ])
+
+Luca.registry.addMetaData = (componentName, key, value)->
+  data = Luca.registry.componentMetaData[ componentName ] ||= {}
+  data[ key ] = _(value).clone()
+  data
+
+class MetaDataProxy
+  constructor: (@meta={})->
+    _.defaults @meta, 
+      "super class name" : ""
+      "display name" : ""
+      "public interface" : []
+      "public configuration" : [] 
+      "private interface" : []
+      "private configuration" : [] 
+      "class configuration" : []
+      "class interface" : []
+
+  superClass: ()->
+    Luca.util.resolve(@meta["super class name"])
+
+  componentDefinition: ()->
+    Luca.registry.find @meta["display name"]
+
+  componentPrototype: ()->
+    @componentDefinition()?.prototype
+
+  prototypeFunctions: ()->
+    _.functions( @componentPrototype() )
+
+  classAttributes: ()->
+    _.uniq @classInterface().concat( @classConfiguration() )
+
+  publicAttributes: ()->
+    _.uniq @publicInterface().concat( @publicConfiguration() )
+
+  privateAttributes: ()->
+    _.uniq @privateInterface().concat( @privateConfiguration() )
+
+  classMethods: ()->
+    list = _.functions( @componentDefinition() )
+    _( list ).intersection( @classAttributes() )
+
+  publicMethods: ()->
+    _( @prototypeFunctions() ).intersection( @publicAttributes() )
+
+  privateMethods: ()->
+    _( @prototypeFunctions() ).intersection( @privateAttributes() )
+
+  classConfiguration: ()->
+    @meta["class configuration"]
+
+  publicConfiguration: ()->
+    @meta["public configuration"]
+
+  privateConfiguration: ()->
+    @meta["private configuration"]
+
+  classInterface: ()->
+    @meta["class interface"]
+
+  publicInterface: ()->
+    @meta["public interface"]
+
+  privateInterface: ()->
+    @meta["private interface"]
+
+  triggers: ()->
+    @meta["hooks"]
+
+  hooks: ()->
+    @meta["hooks"]
+
+  styleHierarchy: ()->
+    list = _( @classHierarchy() ).map (cls)->
+      Luca.util.toCssClass(cls, 'views', 'components', 'core','fields','containers')
+
+    _( list ).without('backbone-view','luca-view')
+      
+  classHierarchy: ()->
+    list = [ @meta["display name"], @meta["super class name"]]
+
+    proxy = @superClass()?.prototype?.componentMetaData?()
+
+    until not proxy
+      list = list.concat( proxy?.classHierarchy() )
+      proxy = proxy.superClass()?.prototype?.componentMetaData?()
+
+    _( list ).uniq()

data/src/core/model.coffee

@@ -8,12 +8,13 @@ model.defines
   initialize: ()->
     Backbone.Model::initialize(@, arguments)
     setupComputedProperties.call(@)
+    Luca.concern.setup.call(@)
 
   read: (attr)->
     if _.isFunction(@[attr])
       @[attr].call(@)
     else
-      @get(attr)
+      @get(attr) || @[attr]
 
   get: (attr)->
     if @computed?.hasOwnProperty(attr)
@@ -37,3 +38,19 @@ setupComputedProperties = ()->
         @trigger "change:#{attr}"
         
       @trigger "change:#{attr}" if @has(dep) 
+
+
+Luca.Model._originalExtend = Backbone.Model.extend
+
+Luca.Model.extend = (definition={})->
+  # for backward compatibility
+  definition.concerns ||= definition.concerns if definition.concerns?
+
+  componentClass = Luca.Model._originalExtend.call(@, definition)
+  
+  if definition.concerns? and _.isArray( definition.concerns )
+    for module in definition.concerns
+      Luca.decorate( componentClass ).with( module )
+
+  componentClass
+

data/src/core/registry.coffee

@@ -76,10 +76,8 @@ Luca.registry.namespaces = (resolve=true)->
   _( registry.namespaces ).map (namespace)->
     if resolve then Luca.util.resolve( namespace ) else namespace
 
-
-
 # Lookup a component in the Luca component registry
-# by it's ctype identifier.  If it doesn't exist,
+# by it's type identifier.  If it doesn't exist,
 # check any other registered namespace
 Luca.registry.lookup = (ctype)->
   if alias = Luca.registry.aliases[ ctype ] 
@@ -119,6 +117,9 @@ Luca.registry.classes = (toString=false)->
       className: className
       ctype: ctype
 
+Luca.registry.find = (search)->
+  Luca.util.resolve(search) || Luca.define.findDefinition(search)
+
 Luca.cache = Luca.cacheInstance = (cacheKey, object)->
   return unless cacheKey?
   return object if object?.doNotCache is true

data/src/core/view.coffee

@@ -4,9 +4,9 @@ view.extends            "Backbone.View"
 
 # includes are extensions to the prototype, and have no special behavior
 view.includes           "Luca.Events",
-                        "Luca.modules.DomHelpers"
+                        "Luca.concerns.DomHelpers"
 
-# mixins are includes with special property / method conventions
+# concerns are includes with special property / method conventions
 # which customize the components through the use of __initializer and
 # __included method names.  These will be called every time an instance
 # is created, and the first time the mixin is used to enhance a component.
@@ -48,16 +48,12 @@ view.defines
 
     @setupHooks _( Luca.View::hooks.concat( @hooks ) ).uniq()
 
-    @setupMixins()
-    @delegateEvents()
+    Luca.concern.setup.call(@)
 
+    @delegateEvents()
+        
     @trigger "after:initialize", @
 
-  setupMixins: ()->
-    if @mixins?.length > 0
-      for module in @mixins 
-        Luca.mixin(module)?.__initializer?.call(@, @, module)
-
   #### Hooks or Auto Event Binding
   #
   # views which inherit from Luca.View can define hooks
@@ -71,18 +67,7 @@ view.defines
   # after:render      : afterRender()
   # after:initialize  : afterInitialize()
   # first:activation  : firstActivation()
-  setupHooks: (set)->
-    set ||= @hooks
-
-    _(set).each (eventId)=>
-      fn = Luca.util.hook( eventId )
-
-      callback = ()->
-        @[fn]?.apply @, arguments
-
-      callback = _.once(callback) if eventId?.match(/once:/)
-
-      @on eventId, callback, @
+  setupHooks: Luca.util.setupHooks
 
   registerEvent: (selector, handler)->
     @events ||= {}
@@ -92,9 +77,14 @@ view.defines
   definitionClass: ()->
     Luca.util.resolve(@displayName, window)?.prototype
 
-  collections: ()-> Luca.util.selectProperties( Luca.isBackboneCollection, @ )
-  models: ()-> Luca.util.selectProperties( Luca.isBackboneModel, @ )
-  views: ()-> Luca.util.selectProperties( Luca.isBackboneView, @ )
+  collections: ()-> 
+    Luca.util.selectProperties( Luca.isBackboneCollection, @ )
+
+  models: ()-> 
+    Luca.util.selectProperties( Luca.isBackboneModel, @ )
+
+  views: ()-> 
+    Luca.util.selectProperties( Luca.isBackboneView, @ )
 
   debug: (args...)->
     return unless @debugMode or window.LucaDebugMode?
@@ -165,14 +155,18 @@ bindEventHandlers = (events={})->
     if _.isString(handler)
       _.bindAll @, handler
 
-Luca.View.extend = (definition)->
+Luca.View.deferrableEvent = "reset"
+
+Luca.View.extend = (definition={})->
   definition = Luca.View.renderWrapper( definition )
+  # for backward compatibility
+  definition.concerns ||= definition.concerns if definition.concerns?
 
-  if definition.mixins? and _.isArray( definition.mixins )
-    for module in definition.mixins
-      Luca.decorate( definition ).with( module )
+  componentClass = Luca.View._originalExtend.call(@, definition)
 
-  Luca.View._originalExtend.call(@, definition)
+  if definition.concerns? and _.isArray( definition.concerns )
+    for module in definition.concerns
+      Luca.decorate( componentClass ).with( module )
 
+  componentClass
 
-Luca.View.deferrableEvent = "reset"

data/src/define.coffee

@@ -1,25 +1,39 @@
 # Component Definition Helpers
 #
-#
 # We have customized the core Backbone.extend process to use a slightly
 # different syntax, which allows us to intercept the component definition at
 # various points, and maintain information about classes being defined, and
 # the relationships between inherited classes, etc.
+#
+# Under the hood it isn't much more than Backbone.View.extend(@proto)  
+#
+# Luca provides a self-documenting component generation language which
+# allows you to build the @proto property in a way which captures the intent
+# of the interface being described.  
+#
+# Example:
+#   myForm = MyApp.register    'MyForm'
+# 
+#   myForm.extends             'Luca.components.FormView'
+#
+#   myForm.triggers            'some:custom:hook'
+#
+#   myForm.publicMethods
+#     publicMethod: ()-> ...
+#
+#   myForm.classMethods 
+#     classMethod: ()-> ...
+#
+# This gives us the ability to inspect our component registry at run time,
+# auto-generate nice documentation, build development tools, etc.
 
-# _.def, or Luca.define returns a chainable object which allows you to define
-# your components with a readable syntax.  For example:
-
-# _.def("Luca.View").extends("Backbone.View").with the_good:"shit"
-# _.def("MyView").extends("Luca.View").with the_custom:"shit"
-_.mixin
-  def: Luca.component = Luca.define = Luca.register = (componentName)-> new DefineProxy(componentName)
-
-# The define proxy chain sets up a call to Luca.extend, which is a wrapper around Luca and Backbone component class' extend function.
-class DefineProxy
-  constructor:(componentName)->
+class ComponentDefinition
+  constructor:(componentName, @autoRegister=true)->
     @namespace = Luca.util.namespace()
     @componentId = @componentName = componentName
     @superClassName = 'Luca.View' 
+    @properties ||= {}
+    @_classProperties ||= {}
 
     if componentName.match(/\./)
       @namespaced = true
@@ -30,6 +44,31 @@ class DefineProxy
       # automatically add the namespace to the namespace registry
       Luca.registry.addNamespace( parts.join('.') )
 
+    Luca.define.__definitions.push(@)
+
+  @create: (componentName, autoRegister=Luca.config.autoRegister)->
+    new ComponentDefinition(componentName, autoRegister)
+
+  isValid: ()->
+    return false unless _.isObject(@properties) 
+    return false unless Luca.util.resolve(@superClassName)?
+    return false unless @componentName?
+    true
+
+  isDefined: ()->
+    @defined is true
+
+  isOpen: ()->
+    !!(@isValid() and not @isDefined())
+
+  meta: (key, value)->
+    metaKey = @namespace + '.' + @componentId
+    metaKey = metaKey.replace(/^\./,'')
+    data = Luca.registry.addMetaData(metaKey, key, value)
+
+    @properties.componentMetaData = ()->
+      Luca.registry.getMetaDataFor(metaKey)
+
   # allow for specifying the namespace
   in: (@namespace)-> @
 
@@ -43,6 +82,7 @@ class DefineProxy
     for hook in hooks
       @properties.hooks.push(hook) 
     @properties.hooks = _.uniq(@properties.hooks)
+    @meta("hooks", @properties.hooks)
     @
 
   includes: (includes...)->
@@ -50,16 +90,69 @@ class DefineProxy
     for include in includes
       @properties.include.push(include) 
     @properties.include = _.uniq(@properties.include)
+    @meta("includes", @properties.include)
+    @
+
+  mixesIn: (concerns...)->
+    _.defaults(@properties ||= {}, concerns: []) 
+    for concern in concerns
+      @properties.concerns.push(concern) 
+    @properties.concerns = _.uniq(@properties.concerns)
+
+    @meta("concerns", @properties.concerns)
+    @
+
+  contains: (components...)->
+    _.defaults(@properties, components: [])
+    @properties.components = components 
+    @
+
+  validatesConfigurationWith:(validationConfiguration={})->
+    @meta "configuration validations", validationConfiguration
+    @properties.validatable = true
+    @
+
+  beforeDefinition: (callback)->
+    @_classProperties.beforeDefinition = callback  
+    @
+
+  afterDefinition: (callback)->
+    @_classProperties.afterDefinition = callback  
+    @
+
+  classConfiguration: (properties={})->
+    @meta("class configuration", _.keys(properties))
+    _.defaults((@_classProperties||={}), properties)
+    @
+
+  publicConfiguration: (properties={})->
+    @meta("public configuration", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  privateConfiguration: (properties={})->
+    @meta("private configuration", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  classInterface: (properties={})->
+    @meta("class interface", _.keys(properties))
+    _.defaults((@_classProperties||={}), properties)
     @
 
-  mixesIn: (mixins...)->
-    _.defaults(@properties ||= {}, mixins: []) 
-    for mixin in mixins
-      @properties.mixins.push(mixin) 
-    @properties.mixins = _.uniq(@properties.mixins)
+  publicInterface: (properties={})->
+    @meta("public interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
     @
 
-  defaultProperties: (properties={})->
+  privateInterface: (properties={})->
+    @meta("private interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  # This is the end of the chain. It MUST be called
+  # in order for the component definition to be complete. 
+  definePrototype: (properties={})->
     _.defaults((@properties||={}), properties)
 
     at = if @namespaced
@@ -72,31 +165,74 @@ class DefineProxy
       eval("(window||global).#{ @namespace } = {}")
       at = Luca.util.resolve(@namespace,(window || global))
 
-    at[@componentId] = Luca.extend(@superClassName,@componentName, @properties)
+    @meta("super class name", @superClassName )
+    @meta("display name", @componentName)
+
+    @properties.displayName = @componentName
+    
+    @properties.componentMetaData = ()->
+      Luca.registry.getMetaDataFor(@displayName)
+
+    @_classProperties?.beforeDefinition?(@)
+
+    definition = at[@componentId] = Luca.extend(@superClassName,@componentName, @properties)
 
-    if Luca.autoRegister is true 
-      componentType = "view" if Luca.isViewPrototype( at[@componentId] )
+    if @autoRegister is true 
+      componentType = "view" if Luca.isViewPrototype( definition )
 
-      if Luca.isCollectionPrototype( at[@componentId] )
+      if Luca.isCollectionPrototype( definition )
         Luca.Collection.namespaces ||= []
         Luca.Collection.namespaces.push( @namespace )
         componentType = "collection" 
 
-      componentType = "model" if Luca.isModelPrototype( at[@componentId] )
+      componentType = "model" if Luca.isModelPrototype( definition )
 
       # automatically register this with the component registry
       Luca.registerComponent( _.string.underscored(@componentId), @componentName, componentType)
 
-    at[@componentId]
+    @defined = true
+
+    unless _.isEmpty(@_classProperties)
+      _.extend(definition, @_classProperties)
+
+    definition?.afterDefinition?.call(definition, @)
+
+    definition
+
 
 # Aliases for the mixin definition
-DefineProxy::behavesAs = DefineProxy::uses = DefineProxy::mixesIn 
+cd = ComponentDefinition::
+
+cd.concerns = cd.behavesAs = cd.uses = cd.mixesIn 
 
 # Aliases for the final call on the define proxy
-DefineProxy::defines = DefineProxy::defaults = DefineProxy::exports = DefineProxy::defaultProperties 
-DefineProxy::defaultsTo = DefineProxy::enhance = DefineProxy::with = DefineProxy::defaultProperties
+cd.register = cd.defines = cd.defaults = cd.exports = cd.defaultProperties = cd.definePrototype
+
+cd.defaultsTo = cd.enhance = cd.with = cd.definePrototype
+
+cd.publicMethods = cd.publicInterface
+cd.privateMethods = cd.privateInterface
+cd.classMethods = cd.classInterface
 
-# The last method of the DefineProxy chain is always going to result in
+_.extend (Luca.define = ComponentDefinition.create),
+  __definitions: []
+  incomplete: ()->
+    _( Luca.define.__definitions ).select (definition)-> 
+      definition.isOpen()
+  close: ()->
+    for open in Luca.define.incomplete()
+      open.register() if open.isValid()
+    Luca.define.__definitions.length = 0
+  findDefinition: (componentName)->
+    _( Luca.define.__definitions ).detect (definition)->
+      definition.componentName is componentName
+
+Luca.register = (componentName)->
+  new ComponentDefinition(componentName, true)
+
+_.mixin def: Luca.define
+
+# The last method of the ComponentDefinition chain is always going to result in
 # a call to Luca.extend.  Luca.extend wraps the call to Luca.View.extend,
 # or Backbone.Collection.extend, and accepts the names of the extending,
 # and extended classes as strings.  This allows us to maintain information
@@ -105,8 +241,6 @@ DefineProxy::defaultsTo = DefineProxy::enhance = DefineProxy::with = DefineProxy
 Luca.extend = (superClassName, childName, properties={})->
   superClass = Luca.util.resolve( superClassName, (window || global) )
 
-  superClass.__initializers ||= []
-
   unless _.isFunction(superClass?.extend)
     throw "Error defining #{ childName }. #{ superClassName } is not a valid component to extend from"
 
@@ -117,9 +251,8 @@ Luca.extend = (superClassName, childName, properties={})->
     superClass
 
   properties._super = (method, context=@, args=[])->
-    # protect against a stack too deep error in weird cases
     # TODO: debug this better
-    
+    # protect against a stack too deep error in weird cases
     @_superClass().prototype[method]?.apply(context, args)
 
   definition = superClass.extend(properties)
@@ -133,50 +266,3 @@ Luca.extend = (superClassName, childName, properties={})->
 
   definition
 
-
-Luca.mixin = (mixinName)->
-  namespace = _( Luca.mixin.namespaces ).detect (space)->
-    Luca.util.resolve(space)?[ mixinName ]?
-
-  namespace ||= "Luca.modules"
-
-  resolved = Luca.util.resolve(namespace)[ mixinName ]
-
-  console.log "Could not find #{ mixinName } in ", Luca.mixin.namespaces unless resolved?
-
-  resolved
-
-Luca.mixin.namespaces = [
-  "Luca.modules"
-]
-
-Luca.mixin.namespace = (namespace)->
-  Luca.mixin.namespaces.push(namespace)
-  Luca.mixin.namespaces = _( Luca.mixin.namespaces ).uniq()
-
-# Luca.decorate('Luca.View').with('Luca.modules.MyCustomMixin')
-Luca.decorate = (componentPrototype)->
-  componentPrototype = Luca.util.resolve(componentPrototype).prototype if _.isString(componentPrototype)
-  
-  return with: (mixin)->
-    mixinDefinition = Luca.mixin(mixin)
-
-    mixinPrivates   = _( mixinDefinition ).chain().keys().select (key)-> 
-      "#{ key }".match(/^__/)
-
-    sanitized   = _( mixinDefinition ).omit( mixinPrivates.value() )
-
-    _.extend(componentPrototype, sanitized)
-
-    # When a mixin is included, we may want to do things 
-    mixinDefinition?.__included?.call(mixinDefinition, mixin) 
-
-    superclassMixins = componentPrototype._superClass()::mixins
-
-    componentPrototype.mixins ||= []
-    componentPrototype.mixins.push( mixin )
-    componentPrototype.mixins = componentPrototype.mixins.concat( superclassMixins )
-
-    componentPrototype.mixins = _( componentPrototype.mixins ).chain().uniq().compact().value()
-
-    componentPrototype