Merge pull request #2 from bitovi-components/doc-improvements

Doc improvements
bitovi-components · Mar 26, 2015 · 58f1bb0 · 58f1bb0
2 parents 4e0060e + 9dcb82a
commit 58f1bb0
Show file tree

Hide file tree

Showing 8 changed files with 140 additions and 115 deletions.
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -10,7 +10,7 @@ module.exports = function (grunt) {
   	grunt.loadNpmTasks('documentjs');
 
 	var config = {
-		documentjs:{},
+		docConfig: docConfig,
 		testee: {
 			options: {
 				reporter: 'Spec'

diff --git a/index.html b/index.html
@@ -1,52 +1,65 @@
 <!-- Template to load -->
 <script type="text/stache" id="demo" can-autorender>
-  <can-import from="bit-autocomplete"/>
-  <bit-autocomplete model="{Search}" selected-item="{selectedItem}" validated="{validated}" debounce-delay="1000"></bit-autocomplete>
-  <p>{{#validated}}You selected {{selectedItem.label}}.{{else}}Do a search then select an item...{{/validated}}</p>
+<can-import from="bit-autocomplete"/><bit-autocomplete
+  model="{Search}"
+  selected-item="{selectedItem}"
+  validated="{validated}">
+</bit-autocomplete>
+<p>
+  {{#validated}}
+    You selected {{selectedItem.label}}.
+  {{else}}
+    Do a search then select an item...
+  {{/validated}}
+</p>
 </script>
 
 <!-- Loading Script -->
-<script src="./node_modules/steal/steal.js" main="can/view/autorender/">
-	import $ from "jquery";
-	import can from "can";
-    import "can/util/fixture/";
-
-    var fruits = [
-        { label: "Granny Smith Apple"},
-        { label: "McIntosh Apple"},
-        { label: "Fuji Apple"},
-		{ label: "Red Delicious Apple"},
-		{ label: "Pink Lady Apple"},
-		{ label: "Golden Delcicious Apple"},
-		{ label: "Gala Apple"},
-		{ label: "Strawberry"},
-		{ label: "Orange"},
-		{ label: "Plum"},
-		{ label: "Blueberry"},
-		{ label: "Pear"},
-		{ label: "Peach"},
-		{ label: "Tomato"},
-		{ label: "Fig"},
-		{ label: "Watermelon"},
-		{ label: "Melon"},
-		{ label: "Sprite Melon"},
-		{ label: "Lemon"}
-    ];
+<script src="./node_modules/steal/steal.js" id="demo_source" main="can/view/autorender/">
+import $ from "jquery";
+import can from "can";
+import "can/util/fixture/";
 
-    can.fixture('GET /test', function(req) {
-        var filtered = fruits.filter(function(item) {
-            return item.label.toLowerCase().indexOf(req.data.label.toLowerCase()) > -1;
-        });
-        return filtered;
-    });
-
-    var Search = can.Model.extend({
-        findAll: "GET /test"
-    },{});
-
-    $("#demo").viewModel().attr({
-        Search: Search,
-        selectedItem: {},
-        valdated: false
-    });
+var fruits = [
+  { label: "Granny Smith Apple"},
+  { label: "McIntosh Apple"},
+  { label: "Fuji Apple"},
+  { label: "Red Delicious Apple"},
+  { label: "Pink Lady Apple"},
+  { label: "Golden Delcicious Apple"},
+  { label: "Gala Apple"},
+  { label: "Strawberry"},
+  { label: "Orange"},
+  { label: "Plum"},
+  { label: "Blueberry"},
+  { label: "Pear"},
+  { label: "Peach"},
+  { label: "Tomato"},
+  { label: "Fig"},
+  { label: "Watermelon"},
+  { label: "Melon"},
+  { label: "Sprite Melon"},
+  { label: "Lemon"}
+];
+
+can.fixture('GET /test', function(req) {
+  var filtered = fruits.filter(function(item) {
+    return item.label.toLowerCase().indexOf(req.data.label.toLowerCase()) > -1;
+  });
+  return filtered;
+});
+
+var Search = can.Model.extend({
+  findAll: "GET /test"
+},{});
+
+$("#demo").viewModel().attr({
+  Search: Search,
+  selectedItem: {},
+  valdated: false
+});
+</script>
+<script>
+  window.DEMO_HTML = document.getElementById("demo").innerHTML.replace('<can-import from="bit-autocomplete"/>', '');
+  window.DEMO_SOURCE = document.getElementById("demo_source").innerHTML;
 </script>
diff --git a/package.json b/package.json
@@ -18,26 +18,28 @@
     "prepublish": "./node_modules/.bin/grunt build"
   },
   "dependencies": {
-    "can": "bitovi/canjs",
+    "can": "2.2.1",
     "cssify": "^0.6.0",
     "lodash": "^3.5.0"
   },
   "devDependencies": {
     "bower": "1.3.8",
+    "documentjs": "^0.3.0-pre.1",
     "grunt": "~0.4.1",
     "grunt-cli": "^0.1.13",
     "grunt-serve": "^0.1.6",
     "jquery": ">1.9.0",
-    "qunitjs": "^1.17.1",
     "steal": "^0.7.1",
+    "steal-qunit": "0.0.3",
     "steal-tools": "^0.7.1",
     "testee": "^0.1.8"
   },
   "system": {
     "main": "bit-autocomplete",
     "npmIgnore": [
       "testee",
-      "cssify"
+      "cssify",
+      "documentjs"
     ],
     "directories": {
       "lib": "src"

diff --git a/src/bit-autocomplete.js b/src/bit-autocomplete.js
@@ -1,6 +1,9 @@
 /**
  * @module {can.Component} autocomplete Autocomplete
  * @parent components
+ * @group autocomplete/events 0 Events
+ * @group autocomplete/viewModel 1 ViewModel
+ *
  * @author Juan Orozco
  *
  *
@@ -11,10 +14,11 @@
  * @signature '<bit-autocomplete></bit-autocomplete>'
  *
  * @param {can.Model} model Contains the model to search with.
- * @param {String} searchFieldId The ID of the input element.
+ * @param {String} search-field-id The ID of the input element.
  * @param {boolean} validited Marks when a selection is made.
- * @param {can.Map} selectedItem The selected item object.
- *
+ * @param {can.Map} selected-item The selected item object.
+ * @param {Number} debounce-delay The amount of time to wait before searching.
+ * @param {Number} character-delay The number of characters that must be entered to trigger a search.
  *
  * @body
  *
@@ -43,9 +47,10 @@ can.Component.extend({
 	template: template,
 	viewModel: ViewModel,
     events: {
-		
+
         /**
-		 * @function autocomplete.searchField Search Field Input Event
+		 * @function autocomplete.events.searchField Search Field Input Event
+         * @parent autocomplete/events
          * @description Runs pre flight on input event of search field.
 		 * @param {selector} $el The element the event was triggered on.
          */
@@ -54,9 +59,10 @@ can.Component.extend({
 			vm.attr('validated', false);
             vm.preFlight( $el.val() );
         },
-		
+
         /**
-		 * @function autocomplete.selectedItem Selected Item Change Event
+		 * @function autocomplete.events.selectedItem Selected Item Change Event
+         * @parent autocomplete/events
          * @description Clears results when a selection is updated.
 		 * @param {can.Map} scope The element scope.
 		 * @param {string} key The key name of the scope property.

diff --git a/src/viewmodel.js b/src/viewmodel.js
@@ -1,26 +1,13 @@
-/**
- * @module {can.Map} autocomplete/ViewModel View Model
- * @parent autocomplete
- * @author Juan Orozco
- *
- * @description View model of the [autocomplete] component.
- *
- * @signature
- * var ViewModel = can.Map.extend({});
- *
- */
 import can from 'can';
 import _ from 'lodash';
 import 'can/map/define/';
 
 export default can.Map.extend({
-    init: function () {
-        this.doSearch = _.debounce( can.proxy(this.doSearch, this), this.attr('debounceDelay') );
-    },
     define:{
 
         /**
-         * @property {can.List} autocomplete.scope.results results
+         * @property {can.List} autocomplete.viewModel.results results
+         * @parent autocomplete/viewModel
          * @description Only true when a selection is intact.
          * @option {can.List} Defaults to `false`.
          */
@@ -29,7 +16,8 @@ export default can.Map.extend({
         },
 
         /**
-         * @property {can.Map} autocomplete.scope.selectedItem selectedItem
+         * @property {can.Map} autocomplete.viewModel.selectedItem selectedItem
+         * @parent autocomplete/viewModel
          * @description Only true when a selection is intact.
          * @option {can.Map} Defaults to `false`.
          */
@@ -38,7 +26,8 @@ export default can.Map.extend({
         },
 
         /**
-         * @property {Boolean} autocomplete.scope.validated validated
+         * @property {Boolean} autocomplete.viewModel.validated validated
+         * @parent autocomplete/viewModel
          * @description Only true when a selection is intact.
          * @option {Boolean} Defaults to `false`.
          */
@@ -48,59 +37,69 @@ export default can.Map.extend({
         },
 
         /**
-         * @property {string} autocomplete.scope.searchKey searchKey
+         * @property {String} autocomplete.viewModel.searchKey searchKey
+         * @parent autocomplete/viewModel
          * @description The primary key to use in search and displaying.
-         * @option {string} Defaults to `label`.
+         * @option {String} Defaults to `label`.
          */
         searchKey:{
             value:'label',
             type: 'string'
         },
 
         /**
-         * @property {number} autocomplete.scope.characterDelay characterDelay
+         * @property {number} autocomplete.viewModel.characterDelay characterDelay
+         * @parent autocomplete/viewModel
          * @description The number of characters before search calls are made.
          * @option {number} Defaults to `5`.
          */
         characterDelay: {
-            value: 5,
+            value: 3,
             type: 'number'
         },
 
         /**
-         * @property {number} autocomplete.scope.debounceDelay debounceDelay
+         * @property {number} autocomplete.viewModel.debounceDelay debounceDelay
+         * @parent autocomplete/viewModel
          * @description The number to delay between calls.
-         * @option {number} Defaults to `400` milliseconds.
+         * @option {number} Defaults to `250` milliseconds.
          */
         debounceDelay: {
-            value: 400,
-            type: 'number'
+            value: 250,
+            type: 'number',
+            set: function(newVal){
+                this.doSearch = _.debounce( can.proxy(this.search, this), newVal );
+                return newVal;
+            }
         },
 
         /**
-         * @property {string} autocomplete.scope.searchFieldId searchFieldId
+         * @property {String} autocomplete.viewModel.searchFieldId searchFieldId
+         * @parent autocomplete/viewModel
          * @description The ID for the input element.
-         * @option {string} Defaults to dropdown with a random number suffix.
+         * @option {String} Defaults to autocomplete with a random number suffix.
          */
-
          searchFieldId: {
             value: function () {
                 return 'autocomplete' + Math.floor( Math.random() * 1000000 );
             },
             type: 'string'
          }
     },
-    
+
     /**
+     * @property {can.Map} autocomplete.viewModel.model model
      * @description The search model provided through live binding.
+     * @parent autocomplete/viewModel
      *
      */
     model: {},
 
     /**
-     * @function autocomplete.scope.preFlight preFlight
+     * @function autocomplete.viewModel.preFlight preFlight
+     * @parent autocomplete/viewModel
      * @description Checks if criteria to commit findall has been met, builds and calls search if met.
-     * @param {string} search The search string to send to findAll.
+     * @param {String} search The search string to send to findAll.
      */
     preFlight: function (search) {
         var self = this,
@@ -120,11 +119,20 @@ export default can.Map.extend({
     },
 
     /**
-     * @function autocomplete.scope.doSearch doSearch
+     * @function autocomplete.viewModel.search doSearch
+     * @parent autocomplete/viewModel
+     * @description Debounced search.
+     * @param {String} data The search object for the findAll.
+     */
+    doSearch: function(){},
+
+    /**
+     * @function autocomplete.viewModel.search search
+     * @parent autocomplete/viewModel
      * @description Does the actual search.
-     * @param {string} data The search object for the findAll.
+     * @param {String} data The search object for the findAll.
      */
-    doSearch: function (data) {
+    search: function (data) {
         var self = this,
             Model = self.attr('model'),
             results = self.attr('results'),
@@ -139,9 +147,10 @@ export default can.Map.extend({
 
     /**
      * @function autocomplete.scope.getItem getItem
+     * @parent autocomplete/viewModel
      * @description Helper that uses the search key to find the correct display value.
      * @param {object} ctx The scope context.
-     * @return {string} The actual display value.
+     * @return {String} The actual display value.
      */
     getItem: function (ctx) {
         if ( !can.isEmptyObject(ctx.attr()) ) {
@@ -153,6 +162,7 @@ export default can.Map.extend({
 
     /**
      * @function autocomplete.scope.selectItem selectItem
+     * @parent autocomplete/viewModel
      * @description Does the actual search.
      * @param {object} data The search object for the findAll.
      */
@@ -163,6 +173,7 @@ export default can.Map.extend({
 
     /**
      * @function autocomplete.scope.clearResults clearResults
+     * @parent autocomplete/viewModel
      * @description Clears the results element.
      */
     clearResults: function () {
@@ -171,6 +182,7 @@ export default can.Map.extend({
 
     /**
      * @function autocomplete.scope.clearSelection clearSelection
+     * @parent autocomplete/viewModel
      * @description Clears the selection and resets validated to false.
      */
     clearSelection: function () {