Merge pull request #29 from pebble/release/v0.1.1

Bump version to 0.1.1

.gitignore

@@ -27,3 +27,5 @@ build/Release
 node_modules
 
 tmp
+
+dist

README.md

@@ -1,7 +1,7 @@
 # Clay
 Clay is a JavaScript library that makes it easy to add offline configuration pages to your Pebble apps. All you need to get started is a couple lines of JavaScript and a JSON file; no servers or HTML required. 
 
-Clay will by default automatically handle the 'showConfiguration' and 'webviewclosed' events traditionally implemented by developers to relay configuration settings to the watch side of the app. This step is not required when using Clay, since each config item is given the same `appKey` as defined in `appinfo.json` (or PebbleKit JS Message Keys on CloudPebble), and is automatically transmitted once the configuration page is submitted by the user. Developers can override this behavior by implementing a [custom function](#custom-function).
+Clay will by default automatically handle the 'showConfiguration' and 'webviewclosed' events traditionally implemented by developers to relay configuration settings to the watch side of the app. This step is not required when using Clay, since each config item is given the same `appKey` as defined in `appinfo.json` (or PebbleKit JS Message Keys on CloudPebble), and is automatically transmitted once the configuration page is submitted by the user. Developers can override this behavior by [handling the events manually](#handling-the-showconfiguration-and-webviewclosed-events-manually).
 
 **Clay is still in early development and may be missing some features. We would love your feedback! Pease submit any ideas or features via GitHub Issues.**
 
@@ -9,7 +9,7 @@ Clay will by default automatically handle the 'showConfiguration' and 'webviewcl
 
 Clay will eventually be built into the Pebble SDK. However, while it is still in beta you will need to follow the steps shown below:
 
-1. Download the Clay distribution file from: [dist/clay.js](dist/clay.js).
+1. Download the **clay.js** distribution file from the [latest release](https://github.com/pebble/clay/releases/latest).
 2. Drop `clay.js` in your project's `src/js` directory. 
 3. Create a JSON file called `config.json` and place it in your `src/js` directory. 
 4. In order for JSON files to work you may need to change a line in your `wscript` from `ctx.pbl_bundle(binaries=binaries, js=ctx.path.ant_glob('src/js/**/*.js'))` to `ctx.pbl_bundle(binaries=binaries, js=ctx.path.ant_glob(['src/js/**/*.js', 'src/js/**/*.json']))`.
@@ -27,7 +27,7 @@ Clay will eventually be built into the Pebble SDK. However, while it is still in
 Clay will eventually be built into CloudPebble. However while it is still in beta, you will need to follow some steps
 
 1. Create a new JavaScript file called `clay.js`.
-2. Copy the contents of the Clay distribution file from [dist/clay.js](dist/clay.js) into your newly created `clay.js` file.
+2. Copy the contents from the **clay.js** distribution file found in the [latest release](https://github.com/pebble/clay/releases/latest) into your newly created `clay.js` file.
 3. Create another JavaScript file called `config.js` with the following content. This will act as your config's root array element, from which the rest of the page is built up:
 
   ```javascript
@@ -67,7 +67,7 @@ Your root element **must** be an array. This represents the entire page. Inside
 
 ## Components
 
-![Example](src/images/example.png)
+<img src="src/images/example.png" width="360" title="Example">
 
 ### Section
 
@@ -178,6 +178,7 @@ Standard text input field.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | string | The default value of the input field. |
+| description | string | Optional sub-text to include below the component |
 | attributes | object | An object containing HTML attributes to set on the input field. You can add basic HTML5 validation this way by setting attributes such as `required` or `type`. |
 
 
@@ -215,6 +216,7 @@ Switch for a single item.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | int\|boolean | The default value of the toggle. Defaults to `false` if not specified. |
+| description | string | Optional sub-text to include below the component |
 | attributes | object | An object containing HTML attributes to set on the input field. You can add basic HTML5 validation this way by setting attribute such as `required`. |
 
 
@@ -249,6 +251,7 @@ A dropdown menu containing multiple options.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | string | The default value of the dropdown menu. Must match a value in the `options` array. |
+| description | string | Optional sub-text to include below the component |
 | attributes | object | An object containing HTML attributes to set on the input field. You can add basic HTML5 validation this way by setting attribute such as `required`. |
 | options | array of objects | The options you want to appear in the dropdown menu. Each option is an object with a `label` and `value` property. |
 
@@ -301,6 +304,7 @@ A color picker containing the 64 supported colors on Basalt and Chalk.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | string OR int | The default color. Always use the uncorrected value even if `sunlight` is true. The component will do the conversion internally. |
+| description | string | Optional sub-text to include below the component |
 | sunlight | boolean | Use the color-corrected sunlight color palette if `true`, else the uncorrected version. Defaults to `true` if not specified. |
 
 ##### Example
@@ -332,6 +336,7 @@ A list of options allowing the user can only choose one option to submit.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | string | The default selected item. Must match a value in the `options` array. |
+| description | string | Optional sub-text to include below the component |
 | attributes | object | An object containing HTML attributes to set on the input field. You can add basic HTML5 validation this way by setting attribute such as `required`. |
 | options | array of objects | The options you want to appear in the radio group. Each option is an object with a `label` and `value` property. |
 
@@ -376,6 +381,7 @@ A list of options where a user may choose more than one option to submit.
 | appKey | string (unique) | The AppMessage key matching the `appKey` item defined in your `appinfo.json`.  Set this to a unique string to allow this item to be looked up using `Clay.getItemsByAppKey()` in your custom function. You must set this if you wish for the value of this item to be persisted after the user closes the config page. |
 | label | string | The label that should appear next to this item. |
 | defaultValue | array of strings | The default selected items. Each value must match one in the `options` array. |
+| description | string | Optional sub-text to include below the component |
 | attributes | object | An object containing HTML attributes to set on the input field. You can add basic HTML5 validation this way by setting attribute such as `required`. |
 | options | array of objects | The options you want to appear in the checkbox group. Each option is an object with a `label` and `value` property. |
 
@@ -443,60 +449,75 @@ The submit button for the page. You **MUST** include this component somewhere in
 
 ## Manipulators 
 
-Each component has a **manipulator**. This is a set of methods used to talk to the item on the page. At a minimum, manipulators must have a `.get()` and `.set(value)` method. When the config page is closed, the `.get()` method is run on all components registered with an `appKey` to construct the object sent to the C app. Many of these methods fire an event when the method is called. You can listen for these events with `ClayItem.on()`.
+Each component has a **manipulator**. This is a set of methods used to talk to the item on the page. 
+At a minimum, manipulators must have a `.get()` and `.set(value)` method however there are also methods to assist in interactivity such as `.hide()` and `.disable()`. 
+**NOTE:** There is currently no way to disable or hide an entire section. You must disable/hide each item in the section to achieve this effect. 
+When the config page is closed, the `.get()` method is run on all components registered with an `appKey` to construct the object sent to the C app. 
+Many of these methods fire an event when the method is called. You can listen for these events with `ClayItem.on()`.
 
 #### html
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [string\|HTML] value)` | `ClayItem` | `change` | Sets the content of this item. |
-| `.get()` | `string` | Gets the content of this item. |
+| `.get()` | `string` | | Gets the content of this item. |
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 #### val
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [string] value)` | `ClayItem` | `change` | Sets the value of this item. |
-| `.get()` |  `string` | Gets the content of this item. |
+| `.get()` |  `string` | | Gets the content of this item. |
 | `.disable()` |  `ClayItem` | `disabled` | Prevents this item from being edited by the user. |
 | `.enable()` |  `ClayItem` | `enabled` | Allows this item to be edited by the user. |
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 #### checked
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [boolean\|int] value)` | `ClayItem` | `change` | Check/uncheck the state of this item. |
-| `.get()` | `int` | 1 if checked, 0 if not checked |
+| `.get()` | `int` | | 1 if checked, 0 if not checked |
 | `.disable()` | `ClayItem` | `disabled` | Prevents this item from being edited by the user. |
 | `.enable()` | `ClayItem` | `enabled` | Allows this item to be edited by the user. |
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 #### color
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [string\|int] value)` | `ClayItem` | `change` | Sets the color picker to the provided color. If the value is a string, it must be provided in hex notation eg `'FF0000'`. |
-| `.get()` | `int` | Get the chosen color. This is returned as a number in order to make it easy to use on the watch side using `GColorFromHEX()`. |
+| `.get()` | `int` | | Get the chosen color. This is returned as a number in order to make it easy to use on the watch side using `GColorFromHEX()`. |
 | `.disable()` | `ClayItem` | `disabled` | Prevents this item from being edited by the user. |
 | `.enable()` | `ClayItem` | `enabled` | Allows this item to be edited by the user. |
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 #### radiogroup
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [string] value)` | `ClayItem` | `change` | Checks the radio button that corresponds to the provided value. |
-| `.get()` |  `string` | Gets the value of the checked radio button in the list. |
+| `.get()` |  `string` | | Gets the value of the checked radio button in the list. |
 | `.disable()` | `ClayItem` | `disabled` | Prevents this item from being edited by the user. |
 | `.enable()` | `ClayItem` | `enabled` | Allows this item to be edited by the user. |
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 #### checkboxgroup
 
 | Method | Returns | Event Fired | Description | 
 |--------|---------|-------------| ------------|
 | `.set( [array] value)` | `ClayItem` | `change` | Checks the checkboxes that corresponds to the provided list of values. |
-| `.get()` |  `Array.<string>` | Gets an array of strings representing the list of the values of the checked items |
+| `.get()` |  `Array.<string>` | | Gets an array of strings representing the list of the values of the checked items |
 | `.disable()` | `ClayItem` | `disabled` | Prevents this item from being edited by the user. |
 | `.enable()` | `ClayItem` | `enabled` | Allows this item to be edited by the user. |
-
+| `.hide()` | `ClayItem` | `hide` | Hides the item |
+| `.show()` | `ClayItem` | `show` | Shows the item |
 
 # Extending Clay
 
@@ -591,7 +612,13 @@ module.exports = function(minified) {
     var coolStuffToggle = Clay.getItemByAppKey('cool_stuff');
     toggleBackground.call(coolStuffToggle);
     coolStuffToggle.on('change', toggleBackground);
+    
+    // Hide the color picker for aplite
+    if (Clay.meta.activeWatchInfo.platform === 'aplite') {
+      Clay.getItemByAppKey('background').hide();
+    }
   });
+  
 };
 ```
 
@@ -607,7 +634,11 @@ This is the main way of talking to your generated config page.
 |----------|------|-------------|
 | `.EVENTS.BEFORE_BUILD` | String | Dispatched prior to building the page. |
 | `.EVENTS.AFTER_BUILD` | String | Dispatched after building the page. |
-| `.config` | Array | Reference to the config passed to the constructer and used for generating the page. |
+| `.config` | Array | Reference to the config passed to the constructor and used for generating the page. |
+| `.meta` | Object | Contains information about the current user and watch |
+| `.meta.activeWatchInfo` | watchinfo\|null | An object containing information on the currently connected Pebble smartwatch or null if unavailable. Read more [here](https://developer.pebble.com/docs/js/Pebble/#getActiveWatchInfo). |
+| `.meta.accountToken` | String | A unique account token that is associated with the Pebble account of the current user. Read more [here](https://developer.pebble.com/docs/js/Pebble/#getAccountToken). |
+| `.meta.watchToken` | String | A unique token that can be used to identify a Pebble device. Read more [here](https://developer.pebble.com/docs/js/Pebble/#getWatchToken). |
 
 
 #### Methods
@@ -637,7 +668,7 @@ This is the main way of talking to your generated config page.
 | `.appKey` | String | The ID of the item if provided in the config. |
 | `.config` | Object | Reference to the config passed to the constructer. |
 | `$element` | $Minified | A Minified list representing the root HTML element of the config item. |
-| `$manipulatorTarget` | A Minified list representing the HTML element with **data-manipulator-target** set. This is generally pointing to the main `<input>` element and will be used for binding events. |
+| `$manipulatorTarget` | $Minified | A Minified list representing the HTML element with **data-manipulator-target** set. This is generally pointing to the main `<input>` element and will be used for binding events. |
 
 
 #### Methods

dev/config.js

@@ -24,32 +24,31 @@ module.exports = [
         "type": "input",
         "appKey": "email",
         "defaultValue": "",
-        "label": "Email",
+        "label": "Input Field",
+        "description": "This is a description for the input component. " +
+                       "You can add <strong>html</strong> in here too.",
         "attributes": {
-          "placeholder": "eg: name@domain.com",
-          "limit": 10,
-          "required": "required",
-          type: "email"
+          "placeholder": "Placeholder set with attributes"
         }
       },
       {
         "type": "toggle",
         "appKey": "cool_stuff",
-        "label": "Enable Cool Stuff",
+        "label": "This is a Toggle",
         "defaultValue": false
       },
       {
         "type": "color",
         "appKey": "colorTest",
         "defaultValue": "FF0000",
-        "label": "Background Color",
+        "label": "Standard Color Picker",
         "sunlight": false
       },
       {
         "type": "color",
         "appKey": "sunnyColorTest",
         "defaultValue": "00FF00",
-        "label": "Sunny Color",
+        "label": "Sunny Color Picker",
         "sunlight": true
       }
     ]
@@ -64,46 +63,33 @@ module.exports = [
       {
         "type": "radiogroup",
         "appKey": "radiogroup-test",
-        "label": "Radio test",
+        "label": "Radio Group",
         "options": [
-          { "label": "Test thing one", "value": "one" },
+          { "label": "Test thing", "value": "one" },
           { "label": "Another thing", "value": "two" },
-          { "label": "One really long thing that would not fit", "value": "three" },
-          { "label": "Small", "value": "quote' \"test" },
-          { "label": "Final thing", "value": "three" }
+          { "label": "Final thing with <em>html</em>", "value": "three" }
         ]
       },
       {
         "type": "checkboxgroup",
         "appKey": "checkboxgroup-test",
         "defaultValue": ["quote' \"test", "two"],
-        "label": "Checkbox test",
+        "label": "Checkbox Group",
         "options": [
-          { "label": "Test <strong>thing</strong> one", "value": "one" },
+          { "label": "First thing", "value": "three" },
           { "label": "Another thing", "value": "two" },
-          { "label": "One really long thing that would not fit", "value": "three" },
-          { "label": "Small", "value": "quote' \"test" },
           { "label": "Final thing", "value": "three" }
         ]
       },
-      {
-        "type": "input",
-        "appKey": "date",
-        "defaultValue": "",
-        "label": "Range",
-        "attributes": {
-          type: "range"
-        }
-      },
       {
         "type": "select",
         "appKey": "flavor",
         "defaultValue": "grape",
-        "label": "Favorite Flavor",
+        "label": "Select Menu",
         "options": [
           { "label": "", "value": "" },
           { "label": "Berry", "value": "berry" },
-          { "label": "Grape", "value": "grape" },
+          { "label": "This Option is Selected", "value": "grape" },
           { "label": "Banana", "value": "banana" }
         ],
         "attributes": {

dev/custom-fn.js

@@ -10,9 +10,9 @@ module.exports = function() {
    */
   function toggleBackground() {
     if (this.get()) {
-      Clay.getItemByAppKey('background').enable();
+      Clay.getItemByAppKey('colorTest').enable();
     } else {
-      Clay.getItemByAppKey('background').disable();
+      Clay.getItemByAppKey('colorTest').disable();
     }
   }
 

gulpfile.js

@@ -103,6 +103,7 @@ gulp.task('dev-js', ['js', 'sass'], function() {
     .transform(stringify(stringifyOptions))
     .transform('deamdify')
     .transform(sassify, sassifyOptions)
+    .transform(autoprefixify, autoprefixerOptions)
     .bundle()
     .pipe(source('dev.js'))
     .pipe(gulp.dest('./tmp/'));

index.js

@@ -29,11 +29,17 @@ function Clay(config, customFn, options) {
   self.config = config;
   self.customFn = customFn || function() {};
   self.components = {};
+  self.meta = {
+    activeWatchInfo: null,
+    accountToken: '',
+    watchToken: ''
+  };
 
   // Let Clay handle all the magic
   if (options.autoHandleEvents !== false && typeof Pebble !== 'undefined') {
 
     Pebble.addEventListener('showConfiguration', function() {
+      _populateMeta();
       Pebble.openURL(self.generateUrl());
     });
 
@@ -49,6 +55,23 @@ function Clay(config, customFn, options) {
         console.log(JSON.stringify(error));
       });
     });
+  } else if (typeof Pebble !== 'undefined') {
+    Pebble.addEventListener('ready', function() {
+      _populateMeta();
+    });
+  }
+
+  /**
+   * Populate the meta with data from the Pebble object. Make sure to run this inside
+   * either the "showConfiguration" or "ready" event handler
+   * @return {void}
+   */
+  function _populateMeta() {
+    self.meta = {
+      activeWatchInfo: Pebble.getActiveWatchInfo && Pebble.getActiveWatchInfo(),
+      accountToken: Pebble.getAccountToken(),
+      watchToken: Pebble.getWatchToken()
+    };
   }
 
   /**
@@ -107,7 +130,8 @@ Clay.prototype.generateUrl = function() {
     .replace('$$CUSTOM_FN$$', toSource(this.customFn))
     .replace('$$CONFIG$$', toSource(this.config))
     .replace('$$SETTINGS$$', toSource(settings))
-    .replace('$$COMPONENTS$$', toSource(this.components));
+    .replace('$$COMPONENTS$$', toSource(this.components))
+    .replace('$$META$$', toSource(this.meta));
 
   // if we are in the emulator then we need to proxy the data via a webpage to
   // obtain the return_to.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pebble-clay",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pebble Config Framework",
   "main": "dist/clay.js",
   "directories": {

src/config-page.html

@@ -10,6 +10,7 @@
       window.claySettings = $$SETTINGS$$;
       window.customFn = $$CUSTOM_FN$$;
       window.clayComponents = $$COMPONENTS$$;
+      window.clayMeta = $$META$$;
     </script>
   </head>
   <body>

src/scripts/components/checkboxgroup.js

@@ -8,6 +8,7 @@ module.exports = {
   defaults: {
     label: '',
     options: [],
+    description: '',
     attributes: {}
   }
 };

src/scripts/components/color.js

@@ -6,7 +6,8 @@ module.exports = {
   style: require('../../styles/clay/components/color.scss'),
   manipulator: 'color',
   defaults: {
-    label: ''
+    label: '',
+    description: ''
   },
   initialize: function(minified) {
     var HTML = minified.HTML;

src/scripts/components/input.js

@@ -7,6 +7,7 @@ module.exports = {
   manipulator: 'val',
   defaults: {
     label: '',
+    description: '',
     attributes: {}
   }
 };

src/scripts/components/radiogroup.js

@@ -8,6 +8,7 @@ module.exports = {
   defaults: {
     label: '',
     options: [],
+    description: '',
     attributes: {}
   }
 };

src/scripts/components/select.js

@@ -8,6 +8,7 @@ module.exports = {
   defaults: {
     label: '',
     options: [],
+    description: '',
     attributes: {}
   },
   initialize: function() {
@@ -15,8 +16,10 @@ module.exports = {
 
     var $value = self.$element.select('.value');
 
-    self.on('change', function(ev) {
-      var value = self.$manipulatorTarget.select('option:checked').get('innerHTML');
+    self.on('change', function() {
+      var selectedIndex = self.$manipulatorTarget.get('selectedIndex');
+      var $options = self.$manipulatorTarget.select('option');
+      var value = $options[selectedIndex] && $options[selectedIndex].innerHTML;
       $value.set('innerHTML', value);
     });
   }

src/scripts/components/submit.js

@@ -3,6 +3,7 @@
 module.exports = {
   name: 'submit',
   template: require('../../templates/components/submit.tpl'),
+  style: require('../../styles/clay/components/submit.scss'),
   manipulator: 'html',
   defaults: {
     attributes: {}

src/scripts/components/toggle.js

@@ -7,6 +7,7 @@ module.exports = {
   manipulator: 'checked',
   defaults: {
     label: '',
+    description: '',
     attributes: {}
   }
 };

src/scripts/config-page.js

@@ -11,6 +11,7 @@ var settings = _.extend({}, window.claySettings || {});
 var returnTo = window.returnTo || 'pebblejs://close#';
 var customFn = window.customFn || function() {};
 var clayComponents = window.clayComponents || {};
+var clayMeta = window.clayMeta || {};
 
 var platform = window.navigator.userAgent.match(/android/i) ? 'android' : 'ios';
 document.documentElement.classList.add('platform-' + platform);
@@ -21,7 +22,7 @@ _.eachObj(clayComponents, function(key, component) {
 });
 
 var $mainForm = $('#main-form');
-var clayConfig = new ClayConfig(settings, config, $mainForm);
+var clayConfig = new ClayConfig(settings, config, $mainForm, clayMeta);
 
 // add listeners here
 $mainForm.on('submit', function() {

src/scripts/lib/clay-config.js

@@ -26,9 +26,10 @@ var manipulators = require('./manipulators');
  * @param {Object} settings - setting that were set from a previous session
  * @param {Array|Object} config
  * @param {M} $rootContainer
+ * @param {Object} meta
  * @constructor
  */
-function ClayConfig(settings, config, $rootContainer) {
+function ClayConfig(settings, config, $rootContainer, meta) {
   var self = this;
 
   var _settings = _.copyObj(settings);
@@ -95,6 +96,8 @@ function ClayConfig(settings, config, $rootContainer) {
     return true;
   }
 
+  self.meta = meta;
+
   self.EVENTS = {
     /**
      * Called before framework has initialized. This is when you would attach your
@@ -183,7 +186,6 @@ function ClayConfig(settings, config, $rootContainer) {
 
   // expose the config to allow developers to update it before the build is run
   self.config = config;
-
 }
 
 /**

src/scripts/lib/manipulators.js

@@ -18,6 +18,22 @@ function enable() {
   return this.trigger('enabled');
 }
 
+/**
+ * @returns {ClayEvents}
+ */
+function hide() {
+  this.$element.set('+hide');
+  return this.trigger('hide');
+}
+
+/**
+ * @returns {ClayEvents}
+ */
+function show() {
+  this.$element.set('-hide');
+  return this.trigger('show');
+}
+
 module.exports = {
   html: {
     get: function() {
@@ -26,7 +42,9 @@ module.exports = {
     set: function(value) {
       this.$manipulatorTarget.set('innerHTML', value);
       return this.trigger('change');
-    }
+    },
+    hide: hide,
+    show: show
   },
   val: {
     get: function() {
@@ -37,7 +55,9 @@ module.exports = {
       return this.trigger('change');
     },
     disable: disable,
-    enable: enable
+    enable: enable,
+    hide: hide,
+    show: show
   },
   checked: {
     get: function() {
@@ -48,7 +68,9 @@ module.exports = {
       return this.trigger('change');
     },
     disable: disable,
-    enable: enable
+    enable: enable,
+    hide: hide,
+    show: show
   },
   radiogroup: {
     get: function() {
@@ -61,7 +83,9 @@ module.exports = {
       return this.trigger('change');
     },
     disable: disable,
-    enable: enable
+    enable: enable,
+    hide: hide,
+    show: show
   },
   checkboxgroup: {
     get: function() {
@@ -83,7 +107,9 @@ module.exports = {
       return self.trigger('change');
     },
     disable: disable,
-    enable: enable
+    enable: enable,
+    hide: hide,
+    show: show
   },
   color: {
     get: function() {
@@ -99,6 +125,8 @@ module.exports = {
       return this.trigger('change');
     },
     disable: disable,
-    enable: enable
+    enable: enable,
+    hide: hide,
+    show: show
   }
 };

src/styles/clay/_base.scss

@@ -17,7 +17,24 @@ html, body {
 
 body {
   background-color: $color-gray-2;
-  padding: $item-spacing-v $item-spacing-h;
+  padding: 0 $item-spacing-h $item-spacing-v;
+}
+
+em {
+  font-style: italic;
+}
+
+strong {
+  @include font-pfdin(medium);
+  color: $color-orange;
+}
+
+a {
+  color: $color-gray-8;
+
+  &:hover {
+    color: inherit;
+  }
 }
 
 h1, h2, h3, h4 {
@@ -54,6 +71,7 @@ label {
   display: flex;
   justify-content: space-between;
   align-items: center;
+  padding: $item-spacing-v $item-spacing-h;
 
   .input {
     white-space: nowrap;
@@ -83,35 +101,43 @@ label {
   }
 }
 
-.component {
-  padding-bottom: $item-spacing-v;
+.hide {
+  display: none !important;
+}
+
+.tap-highlight {
   @include tap-highlight();
+}
+
+.component {
+  padding-top: $item-spacing-v;
 
   &.disabled {
-    opacity: 0.25;
     pointer-events: none;
+    > * {
+      opacity: 0.25;
+    }
   }
 }
 
 .section {
   background: $color-gray-4;
   border-radius: 0.25rem;
-  margin-bottom: 1rem;
   box-shadow: $color-gray-1 0 0.15rem 0.25rem;
 
-  .component {
-    padding-top: $item-spacing-v;
+  > .component {
+    padding-bottom: $item-spacing-v;
     padding-right: $item-spacing-h;
     padding-left: $item-spacing-h;
     position: relative;
+    margin-top: 1rem;
 
-    &:last-child,
-    &:first-child {
-      padding-bottom: $item-spacing-v;
-      
-      &:after {
-        display: none;
-      }
+    &:not(.hide) ~ .component {
+      margin-top: 0;
+    }
+
+    &:first-child:after {
+      display: none;
     }
 
     &:after {
@@ -119,7 +145,7 @@ label {
       background: $color-gray-6;
       display: block;
       position: absolute;
-      bottom: 0;
+      top: 0;
       left: $item-spacing-h / 2;
       right: $item-spacing-h / 2;
       height: 1px;
@@ -127,72 +153,41 @@ label {
     }
   }
 
-  .component-heading:first-child {
+  // don't show the separator for the first non-hidden item
+  > .component:not(.hide):after {
+    display: none;
+  }
+
+  > .component:not(.hide) ~ .component:not(.hide):after {
+    display: block;
+  }
+
+  > .component-heading:first-child {
     background: $color-gray-3;
     border-radius: $border-radius $border-radius 0 0;
+
+    // don't show the separator for the first non-hidden item after the heading
+    &:after,
+    ~ .component:not(.hide):after {
+      display: none;
+    }
+
+    ~ .component:not(.hide) ~ .component:not(.hide):after {
+      display: block;
+    }
   }
 
 }
 
-strong {
-  @include font-pfdin(medium);
-  color: $color-orange;
-}
-
-a {
-  color: $color-gray-8;
-
-  &:hover {
-    color: inherit;
-  }
+.description {
+  padding: 0 $item-spacing-h $item-spacing-v ;
+  @include font-size(0.9);
+  color: $color-gray-9;
 }
 
 .inputs {
   display: block;
   width:100%;
   border-collapse: collapse;
-
-  .section & .component {
-    display: table;
-    width:100%;
-
-    .label,
-    .input {
-      display: table-cell;
-    }
-    
-    .input {
-      text-align: right;
-    }
-
-    &.invalid {
-      .input:after {
-        content: "!";
-        display: inline-block;
-        color: $color-white;
-        background: $color-orange;
-        border-radius: $border-radius;
-        width: 1.2em;
-        text-align: center;
-        height: 1.2em;
-        font-size: 1em;
-        vertical-align: middle;
-        line-height: 1.3em;
-        margin-left: -0.7em;
-        position:absolute;
-        @include font-pfdin(regular);
-      }
-
-      .input input {
-        color: $color-orange;
-        padding-right: 1em;
-
-        @include placeholder {
-          color: $color-orange;
-        }
-
-      }
-    }
-
-  }
 }
+

src/styles/clay/_vars.scss

@@ -34,14 +34,7 @@ $color-gray-9: #a4a4a4 ;
 $color-gray-10: #ececec;
 $color-gray-11: #f2f2f2;
 
-
-
-
-$global-margin: 55px;
-$form-margin: 25px;
 $button-padding: 0.7rem;
 $button-padding-ios: 0.6rem;
-$button-line-height: 13px;
-$footer-height-large: 90px;
 
 $box-shadow-small-components: $color-gray-1 0 0.1rem 0.1rem;

src/styles/clay/components/checkboxgroup.scss

@@ -3,9 +3,11 @@
 
 .component-checkbox {
 
-  @include tap-highlight(rgba(0,0,0,0));
   display: block;
 
+  .section & {
+    padding-right: $item-spacing-h / 2;
+  }
 
   > .label {
     display: block;
@@ -14,14 +16,14 @@
 
   .checkbox-group {
 
+    padding-bottom: $item-spacing-v / 2;
+
     label {
-      padding: $item-spacing-v / 2 0;
-      @include tap-highlight();
+      padding: $item-spacing-v / 2 $item-spacing-h / 2;
     }
 
     .label {
       font-size: 0.9em;
-      padding: 0 $item-spacing-h / 2;
     }
 
     input {
@@ -39,7 +41,7 @@
       flex-shrink: 0;
     }
 
-    input:checked ~ i {
+    input:checked + i {
       border-color: $color-orange;
       background: $color-orange;
       
@@ -59,6 +61,10 @@
 
       }
     }
+  }
 
+  .description {
+    padding-left: 0;
+    padding-right: 0;
   }
 }

src/styles/clay/components/color.scss

@@ -2,11 +2,16 @@
 
 .component-color {
 
+  .section & {
+    padding: 0;
+  }
+
   .value {
     width: $small-component-width;
     height: $base-height;
     border-radius: $base-height / 2;
     box-shadow: $box-shadow-small-components;
+    display: block;
   }
 
   .picker-wrap {

src/styles/clay/components/input.scss

@@ -2,7 +2,13 @@
 
 .component-input {
 
-  display: block;
+  .section & {
+    padding: 0;
+  }
+
+  label {
+    display: block;
+  }
 
   .label {
     padding-bottom: $item-spacing-v;

src/styles/clay/components/radiogroup.scss

@@ -3,9 +3,11 @@
 
 .component-radio {
 
-  @include tap-highlight(rgba(0,0,0,0));
   display: block;
 
+  .section & {
+    padding-right: $item-spacing-h / 2;
+  }
 
   > .label {
     display: block;
@@ -14,14 +16,14 @@
 
   .radio-group {
 
+    padding-bottom: $item-spacing-v / 2;
+
     label {
-      padding: $item-spacing-v / 2 0;
-      @include tap-highlight();
+      padding: $item-spacing-v / 2 $item-spacing-h / 2;
     }
 
     .label {
       font-size: 0.9em;
-      padding: 0 $item-spacing-h / 2;
     }
 
     input {
@@ -39,7 +41,7 @@
       flex-shrink: 0;
     }
 
-    input:checked ~ i {
+    input:checked + i {
       border-color: $color-orange;
       
       &:after {
@@ -58,4 +60,9 @@
     }
 
   }
+
+  .description {
+    padding-left: 0;
+    padding-right: 0;
+  }
 }

src/styles/clay/components/select.scss

@@ -2,12 +2,20 @@
 @import "clay";
 
 .component-select {
-  position: relative;
+
+  .section & {
+    padding: 0;
+  }
+
+  label {
+    position: relative;
+  }
 
   .value {
     $triangle-size: 0.85rem;
     position: relative;
     padding-right: $triangle-size + 0.25rem;
+    display: block;
 
     &:after {
       content: "";
@@ -15,7 +23,7 @@
       right: 0;
       top: 50%;
       margin-top: -0.1rem;
-      @include triangle($triangle-size, $color-gray-10, down);
+      @include triangle($triangle-size, $color-orange, down);
     }
   }
 

src/styles/clay/components/submit.scss

@@ -0,0 +1,3 @@
+.component-submit {
+  text-align: center;
+}

src/styles/clay/components/toggle.scss

@@ -6,6 +6,10 @@
   $slide-width: $small-component-width;
   $marker-diameter: $base-height;
 
+  .section & {
+    padding: 0;
+  }
+
   input {
     display: none; // @todo make sure this doesn't mess up interactivity on iOS
   }

src/styles/clay/elements/_button.scss

@@ -9,7 +9,7 @@ button,
   font-size: 1rem;
   line-height: 1;
   border: none;
-  display: block;
+  display: inline-block;
 
   color: $color-white;
   min-width: 12rem;

src/templates/components/checkboxgroup.tpl

@@ -2,7 +2,7 @@
   <span class="label">{{{label}}}</span>
   <div class="checkbox-group">
     {{each options}}
-      <label>
+      <label class="tap-highlight">
         <span class="label">{{{this.label}}}</span>
         <input
           type="checkbox"
@@ -15,4 +15,7 @@
       </label>
     {{/each}}
   </div>
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
 </div>

src/templates/components/color.tpl

@@ -1,5 +1,5 @@
 <div class="component component-color">
-  <label>
+  <label class="tap-highlight">
     <input
       data-manipulator-target
       type="hidden"
@@ -7,6 +7,9 @@
     <span class="label">{{{label}}}</span>
     <span class="value"></span>
   </label>
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
   <div class="picker-wrap">
     <div class="picker">
       <div class="color-box-wrap">

src/templates/components/input.tpl

@@ -1,9 +1,15 @@
-<label class="component component-input">
-  <span class="label">{{{label}}}</span>
-  <span class="input">
-    <input
+<div class="component component-input">
+  <label class="tap-highlight">
+    <span class="label">{{{label}}}</span>
+    <span class="input">
+      <input
       data-manipulator-target
-      {{each key: attributes}}{{key}}="{{this}}"{{/each}}
+        {{each key: attributes}}{{key}}="{{this}}"{{/each}}
     />
-  </span>
-</label>
+    </span>
+  </label>
+
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
+</div>

src/templates/components/radiogroup.tpl

@@ -2,7 +2,7 @@
   <span class="label">{{{label}}}</span>
   <div class="radio-group">
     {{each options}}
-      <label>
+      <label class="tap-highlight">
         <span class="label">{{{this.label}}}</span>
         <input
           type="radio"
@@ -15,4 +15,7 @@
       </label>
     {{/each}}
   </div>
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
 </div>

src/templates/components/select.tpl

@@ -1,9 +1,14 @@
-<label class="component component-select">
-  <span class="label">{{{label}}}</span>
-  <span class="value"></span>
-  <select data-manipulator-target {{each key: attributes}}{{key}}="{{this}}"{{/each}}>
-    {{each options}}
-      <option value="{{this.value}}" class="item-select-option">{{this.label}}</option>
-    {{/each}}
-  </select>
-</label>
+<div class="component component-select">
+  <label class="tap-highlight">
+    <span class="label">{{{label}}}</span>
+    <span class="value"></span>
+    <select data-manipulator-target {{each key: attributes}}{{key}}="{{this}}"{{/each}}>
+      {{each options}}
+        <option value="{{this.value}}" class="item-select-option">{{this.label}}</option>
+      {{/each}}
+    </select>
+  </label>
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
+</div>

src/templates/components/submit.tpl

@@ -1,4 +1,4 @@
-<div class="component component-button">
+<div class="component component-submit">
   <button
     data-manipulator-target
     type="submit"

src/templates/components/toggle.tpl

@@ -1,14 +1,19 @@
-<label class="component component-toggle">
-  <span class="label">{{{label}}}</span>
-  <span class="input">
-    <input
-      data-manipulator-target
-      type="checkbox"
-      {{each key: attributes}}{{key}}="{{this}}"{{/each}}
-    />
-    <span class="graphic">
-      <span class="slide"></span>
-      <span class="marker"></span>
+<div class="component component-toggle">
+  <label class="tap-highlight">
+    <span class="label">{{{label}}}</span>
+    <span class="input">
+      <input
+        data-manipulator-target
+        type="checkbox"
+        {{each key: attributes}}{{key}}="{{this}}"{{/each}}
+      />
+      <span class="graphic">
+        <span class="slide"></span>
+        <span class="marker"></span>
+      </span>
     </span>
-  </span>
-</label>
+  </label>
+  {{if description}}
+    <div class="description">{{{description}}}</div>
+  {{/if}}
+</div>

test/fixture.js

@@ -10,6 +10,29 @@ var components = require('../src/scripts/components');
 var componentRegistry = require('../src/scripts/lib/component-registry');
 var idCounter = 0;
 
+/**
+ * @returns {{accountToken: string, watchToken: string, activeWatchInfo: {platform:
+ *   string, model: string, language: string, firmware: {major: number, minor:
+ *   number, patch: number, suffix: string}}}}
+ */
+module.exports.meta = function() {
+  return {
+    accountToken: '0123456789abcdef0123456789abcdef',
+    watchToken: '0123456789abcdef0123456789abcdef',
+    activeWatchInfo: {
+      platform: 'chalk',
+      model: 'qemu_platform_chalk',
+      language: 'en_US',
+      firmware: {
+        major: 3,
+        minor: 3,
+        patch: 2,
+        suffix: ''
+      }
+    }
+  };
+};
+
 /**
  * @param {string|Object} config
  * @param {boolean} [autoRegister=true]
@@ -70,7 +93,8 @@ module.exports.clayConfig = function(types, build, autoRegister, settings) {
   var clayConfig = new ClayConfig(
     settings || {},
     module.exports.config(types, autoRegister),
-    $(HTML('<div>'))
+    $(HTML('<div>')),
+    module.exports.meta()
   );
   return build === false ? clayConfig : clayConfig.build();
 };

test/spec/index.js

@@ -5,6 +5,21 @@ var Clay = require('../../index');
 var assert = require('chai').assert;
 var standardComponents = require('../../src/scripts/components');
 var sinon = require('sinon');
+var toSource = require('tosource');
+
+var accountToken = '0123456789abcdef0123456789abcdef';
+var watchToken = '0123456789abcdef0123456789abcdef';
+var activeWatchInfo = {
+  platform: 'chalk',
+  model: 'qemu_platform_chalk',
+  language: 'en_US',
+  firmware: {
+    major: 3,
+    minor: 3,
+    patch: 2,
+    suffix: ''
+  }
+};
 
 /**
  * @return {void}
@@ -13,7 +28,10 @@ function stubPebble() {
   global.Pebble = {
     addEventListener: sinon.stub(),
     openURL: sinon.stub(),
-    sendAppMessage: sinon.stub()
+    sendAppMessage: sinon.stub(),
+    getActiveWatchInfo: sinon.stub().returns(activeWatchInfo),
+    getAccountToken: sinon.stub().returns(accountToken),
+    getWatchToken: sinon.stub().returns(watchToken)
   };
 }
 
@@ -56,12 +74,19 @@ describe('Clay', function() {
 
     it('handles the "showConfiguration" event if autoHandleEvents is not false',
     function() {
+      this.timeout(10000); // 10 seconds
+
       stubPebble();
       var clay = fixture.clay([]);
+
+      // we stub the generateUrl method to avoid very large string comparisons.
+      var generateUrlStub = sinon.stub(clay, 'generateUrl');
+      generateUrlStub.returns('data:text/html;base64,PGh0bWw%2BVEVTVDwvaHRtbD4%3D');
       Pebble.addEventListener.withArgs('showConfiguration').callArg(1);
 
       assert(Pebble.addEventListener.calledWith('showConfiguration'));
       assert(Pebble.openURL.calledWith(clay.generateUrl()));
+      generateUrlStub.restore();
     });
 
     it('handles the "webviewclosed" event if autoHandleEvents is not false',
@@ -99,7 +124,14 @@ describe('Clay', function() {
        'if autoHandleEvents is false', function() {
       stubPebble();
       fixture.clay([], null, { autoHandleEvents: false });
-      assert.strictEqual(Pebble.addEventListener.called, false);
+      assert.strictEqual(
+        Pebble.addEventListener.withArgs('webviewclosed').called,
+        false
+      );
+      assert.strictEqual(
+        Pebble.addEventListener.withArgs('showConfiguration').called,
+        false
+      );
     });
   });
 
@@ -117,13 +149,67 @@ describe('Clay', function() {
   });
 
   describe('.generateUrl()', function() {
+
+    /**
+     * Decode the generated data URI into just the HTML portion
+     * @param {string} url
+     * @returns {string}
+     */
+    function decodeUrl(url) {
+      return atob(decodeURIComponent(url.replace(/^.*?[#,]/, '')));
+    }
+
+    describe('string substitutions', function() {
+      var customFn = function() { this.getAllItems(); };
+      var config = fixture.config(['input', 'color']);
+      var settings = { appKey: 'value' };
+      var clay;
+      var html;
+
+      before(function() {
+        stubPebble();
+        clay = fixture.clay(config, customFn);
+        Pebble.addEventListener.withArgs('showConfiguration').callArg(1);
+        localStorage.setItem('clay-settings', JSON.stringify(settings));
+        html = decodeUrl(clay.generateUrl());
+      });
+
+      it('Substitutes $$RETURN_TO$$ with the pebblejs://close#', function() {
+        assert.notInclude(html, '$$RETURN_TO$$');
+        assert.include(html, 'window.returnTo="pebblejs://close#"');
+      });
+
+      it('Substitutes $$CUSTOM_FN$$ with the customFn', function() {
+        assert.notInclude(html, '$$CUSTOM_FN$$');
+        assert.include(html, 'window.customFn=' + toSource(customFn));
+      });
+
+      it('Substitutes $$CONFIG$$ with the config', function() {
+        assert.notInclude(html, '$$CONFIG$$');
+        assert.include(html, 'window.clayConfig=' + toSource(config));
+      });
+
+      it('Substitutes $$SETTINGS$$ with the config', function() {
+        assert.notInclude(html, '$$SETTINGS$$');
+        assert.include(html, 'window.claySettings=' + toSource(settings));
+      });
+
+      it('Substitutes $$COMPONENTS$$ with the config', function() {
+        assert.notInclude(html, '$$COMPONENTS$$');
+        assert.include(html, 'window.clayComponents=' + toSource(clay.components));
+      });
+
+      it('Substitutes $$META$$ with the config', function() {
+        assert.notInclude(html, '$$META$$');
+        assert.include(html, 'window.clayMeta=' + toSource(clay.meta));
+      });
+    });
+
     it('does not replace $$RETURN_TO$$ if in the emulator', function() {
       var clay = fixture.clay([]);
       stubPebble();
       Pebble.platform = 'pypkjs';
-      var decodedUrl =
-        atob(decodeURIComponent(clay.generateUrl().replace(/^.*?#/, '')));
-      assert.match(decodedUrl, /\$\$RETURN_TO\$\$/);
+      assert.match(decodeUrl(clay.generateUrl()), /\$\$RETURN_TO\$\$/);
     });
 
     it('returns the emulator URL if inside emulator', function() {
@@ -170,6 +256,52 @@ describe('Clay', function() {
     });
   });
 
+  describe('.meta', function() {
+    var emptyMeta = {
+      activeWatchInfo: null,
+      accountToken: '',
+      watchToken: ''
+    };
+
+    it('populates the meta in the showConfiguration handler', function() {
+      stubPebble();
+      var clay = fixture.clay([]);
+
+      // meta only gets populated after showConfiguration happens
+      assert.deepEqual(clay.meta, emptyMeta);
+      Pebble.addEventListener.withArgs('showConfiguration').callArg(1);
+
+      assert.deepEqual(clay.meta, {
+        activeWatchInfo: activeWatchInfo,
+        accountToken: accountToken,
+        watchToken: watchToken
+      });
+    });
+
+    it('populates the meta in the ready handler', function() {
+      stubPebble();
+      var clay = fixture.clay([], null, {autoHandleEvents: false});
+
+      // meta only gets populated after ready happens
+      assert.deepEqual(clay.meta, emptyMeta);
+      Pebble.addEventListener.withArgs('ready').callArg(1);
+
+      assert.deepEqual(clay.meta, {
+        activeWatchInfo: activeWatchInfo,
+        accountToken: accountToken,
+        watchToken: watchToken
+      });
+    });
+
+    it('populates the meta with with empty values when there is no Pebble global',
+    function() {
+      delete global.Pebble;
+      var clay = fixture.clay([], null, {autoHandleEvents: false});
+
+      assert.deepEqual(clay.meta, emptyMeta);
+    });
+  });
+
   describe('Clay.encodeDataUri()', function() {
 
     /**

test/spec/lib/clay-config.js

@@ -20,12 +20,20 @@ describe('ClayConfig', function() {
       'build',
       'on',
       'off',
-      'trigger'
+      'trigger',
+      'meta'
     ];
     var clayConfig = fixtures.clayConfig(['input']);
     checkReadOnly(clayConfig, properties);
   });
 
+  describe('.meta', function() {
+    it('populates meta', function() {
+      var clayConfig = fixtures.clayConfig(['input']);
+      assert.deepEqual(clayConfig.meta, fixtures.meta());
+    });
+  });
+
   describe('throws when trying to run methods before being built', function() {
     [
       'getItemByAppKey',

test/spec/lib/clay-item.js

@@ -77,7 +77,7 @@ describe('ClayItem', function() {
   describe('.$element', function() {
     it('sets $element correctly', function() {
       var clayItem = fixture.clayItem('input');
-      assert.strictEqual(clayItem.$element[0].tagName, 'LABEL');
+      assert.strictEqual(clayItem.$element[0].classList.contains('component'), true);
     });
   });
 

test/spec/lib/manipulators.js

@@ -7,7 +7,7 @@ var fixture = require('../../fixture');
 describe('manipulators', function() {
 
   /**
-   * @param {string|Clay~ConfigItem} itemType
+   * @param {string|Object} itemType
    * @param {*} value
    * @param {*} [expected]
    * @return {void}
@@ -31,7 +31,7 @@ describe('manipulators', function() {
   }
 
   /**
-   * @param {string|Clay~ConfigItem} itemType
+   * @param {string|Object} itemType
    * @return {void}
    */
   function testDisable(itemType) {
@@ -57,7 +57,7 @@ describe('manipulators', function() {
   }
 
   /**
-   * @param {string} itemType
+   * @param {string|Object} itemType
    * @return {void}
    */
   function testEnable(itemType) {
@@ -84,14 +84,71 @@ describe('manipulators', function() {
     });
   }
 
+  /**
+   * @param {string|Object} itemType
+   * @return {void}
+   */
+  function testHide(itemType) {
+    describe('.hide()', function() {
+      it('hides the field then triggers a "hide" event', function() {
+        var handlerSpy = sinon.spy();
+        var clayItem = fixture.clayItem(itemType);
+        clayItem.on('hide', handlerSpy);
+
+        assert.strictEqual(
+          clayItem.$element[0].classList.contains('hide'),
+          false
+        );
+        clayItem.hide();
+        assert.strictEqual(
+          clayItem.$element[0].classList.contains('hide'),
+          true
+        );
+        assert.strictEqual(handlerSpy.callCount, 1, 'handler not called once');
+        assert(handlerSpy.calledOn(clayItem), 'handler not called on clayItem');
+      });
+    });
+  }
+
+  /**
+   * @param {string|Object} itemType
+   * @return {void}
+   */
+  function testShow(itemType) {
+    describe('.show()', function() {
+      it('shows the field then triggers a "show" event', function() {
+        var handlerSpy = sinon.spy();
+        var clayItem = fixture.clayItem(itemType);
+        clayItem.on('show', handlerSpy);
+
+        clayItem.hide();
+        assert.strictEqual(
+          clayItem.$element[0].classList.contains('hide'),
+          true
+        );
+        clayItem.show();
+        assert.strictEqual(
+          clayItem.$element[0].classList.contains('hide'),
+          false
+        );
+        assert.strictEqual(handlerSpy.callCount, 1, 'handler not called once');
+        assert(handlerSpy.calledOn(clayItem), 'handler not called on clayItem');
+      });
+    });
+  }
+
   describe('html', function() {
-    testSetGet('footer', 'test123');
+    testSetGet('text', 'test123');
+    testShow('text');
+    testHide('text');
   });
 
   describe('val', function() {
     testSetGet('input', 'test321');
     testDisable('input');
     testEnable('input');
+    testShow('text');
+    testHide('text');
   });
 
   describe('checked', function() {
@@ -101,6 +158,8 @@ describe('manipulators', function() {
     testSetGet('toggle', 0);
     testDisable('toggle');
     testEnable('toggle');
+    testShow('toggle');
+    testHide('toggle');
   });
 
   describe('radiogroup', function() {
@@ -118,6 +177,8 @@ describe('manipulators', function() {
     testSetGet(item, 'three "quote');
     testDisable(item);
     testEnable(item);
+    testShow(item);
+    testHide(item);
   });
 
   describe('checkboxgroup', function() {
@@ -136,6 +197,8 @@ describe('manipulators', function() {
     testSetGet(item, false, []);
     testDisable(item);
     testEnable(item);
+    testShow(item);
+    testHide(item);
   });
 
   describe('color', function() {
@@ -149,5 +212,7 @@ describe('manipulators', function() {
     testSetGet('color', undefined, 0x000000);
     testDisable('color');
     testEnable('color');
+    testShow('color');
+    testHide('color');
   });
 });