bv-ui-core 0.1.1

package/lib/namespacer/README.md

@@ -0,0 +1,57 @@
+# namespacer
+
+The namespacer module provides an interface to create or obtain a namespace
+suitable for use by one or more applications running on the same web page.
+
+```js
+var global = require('bv-ui-core/lib/global');
+var namespacer = require('bv-ui-core/lib/namespacer');
+
+// If the namespace already exists it will be returned. If not it will be
+// created and then returned.
+var namespaceName = 'EXAMPLE';
+var namespace = namespacer.namespace(namespaceName);
+
+// The namespace also exists on the global object once created.
+namespace = global[namespaceName];
+```
+
+## Namespace API
+
+A namespace instance exposes the following methods:
+
+### registerProperty (name, value)
+
+A namespace instance allows for registration of properties to identify unwanted
+collisions. Typically one or more applications will register themselves with the
+namespace on a given web page, but there are also other situations in which
+registration of properties is useful.
+
+```js
+namespace.registerProperty('example', applicationInstance);
+
+// The application is now assigned to namespace.example.
+var exampleApplication = namespace.example;
+
+// Trying to register another value to 'example' in this namespace will throw.
+try {
+  namespace.registerProperty('example', anotherApplicationInstance);
+}
+catch (e) {
+  console.error(e);
+}
+```
+
+## Creating a `namespace` Module
+
+It is good practice for an application to create a `namespace` module that
+exports the namespace used by that application. For example:
+
+```js
+var namespacer = require('bv-ui-core/lib/namespacer');
+
+module.exports = namespacer.namespace('EXAMPLE');
+```
+
+All other code can then require the `namespace` module when access to the
+namespace is needed.

package/lib/namespacer/index.js

@@ -0,0 +1,98 @@
+/**
+ * @fileOverview
+ * A namespace generator.
+ *
+ * @module
+ */
+
+var global = require('../global');
+
+// --------------------------------------------------------------------------
+// Namespace class definition.
+// --------------------------------------------------------------------------
+
+/**
+ * @class
+ * A namespace.
+ *
+ * @param name The name of this Namespace instance. It should be the same as the
+ *   name of the global property to which this namespace is assigned.
+ */
+function Namespace (name) {
+  this.name = name;
+}
+
+/**
+ * Register a property in the namespace, such as an application instance.
+ *
+ * Attempting to register the same property twice is almost always an error, and
+ * thus results in an exception.
+ *
+ * @param {String} name The property name.
+ * @param {Mixed} value The property value.
+ * @return {Namespace} The namespace instance. Useful for chaining.
+ */
+Namespace.prototype.registerProperty = function (name, value) {
+  if (this.hasOwnProperty(name)) {
+    throw new Error(
+      'Cannot register ' + name +
+      ' because a property with that name already exists on window.' +
+      this.name
+    );
+  }
+
+  this[name] = value;
+  return this;
+};
+
+// --------------------------------------------------------------------------
+// Exported interface.
+// --------------------------------------------------------------------------
+
+module.exports = {
+  /**
+   * Obtain a namespace object, creating one if necessary.
+   *
+   * The namespace will be assigned to the global object as a property
+   * with the provided name. i.e. namespacer.namespace('foo') creates or returns
+   * a namespace at global[foo].
+   *
+   * @param {String} name The namespace name.
+   * @return {Mixed} The namespace.
+   */
+  namespace: function (name) {
+    // If there is no global property yet assigned for this namespace then
+    // create one.
+    if (global[name] === undefined) {
+      Object.defineProperty(global, name, {
+        value: new Namespace(name)
+      });
+    }
+    // If an object already exists for this global property, check to see
+    // whether or not it is a Namespace instance or some other form of object.
+    else if (typeof global[name] === 'object') {
+      // If the existing object is not a Namespace instance, then provide it
+      // with the necessary decorations and capabilies of a Namespace instance.
+      //
+      // Other code may have a reference to the object, so we can't do anything
+      // more drastic such as replacing it.
+      if (!(global[name] instanceof Namespace)) {
+        Namespace.call(global[name], name);
+        for (var prop in Namespace.prototype) {
+          global[name][prop] = Namespace.prototype[prop];
+        }
+      }
+    }
+    // If something other than undefined or an object is assigned to this global
+    // property then assume that other code is using it for another purpose, so
+    // throw.
+    else {
+      throw new Error(
+        'Namespace ' + name + ' cannot be created.' +
+        ' A non-object variable is already assigned to window.' + name
+      );
+    }
+
+    return global[name];
+  }
+};

package/lib/performance/README.md

@@ -0,0 +1,35 @@
+# Performance
+
+Provides a cross-browser safe way to use the Navigation Timing API.
+
+## Performance/now
+
+Ported from Bazaarvoice internal code and based on [a Paul Irish polyfill][1].
+
+### Usage
+
+```javascript
+var perfNow = require('performance/now.js');
+
+var timing = perfNow.now();
+```
+
+### Notes
+
+This is not a true polyfill in browsers that do not implement the Navigation
+Timing API. Rather than returning the time elapsed since `navigationStart`, it
+will return the time elapsed since the polyfill was installed.
+
+## Performance/mark
+
+Also ported from Bazaarvoice internal code.
+
+### Usage
+
+```javascript
+var perfMark = require('performance/mark.js');
+
+perfMark.mark('mark-name');
+```
+
+[1]: https://gist.github.com/paulirish/5438650

package/lib/performance/entries.js

@@ -0,0 +1,5 @@
+var timeline = [];
+
+module.exports = {
+  timeline: timeline
+};

package/lib/performance/getEntries.js

@@ -0,0 +1,42 @@
+/**
+ *  @fileOverview
+ *  Performance.getEntries uses the native User Timing API
+ *  when available and falls back to a manual implementation if not
+ */
+
+// Imports
+var global = require('../global');
+var timeline = require('./entries').timeline;
+
+// Determine now (once) if we can use the native User Timing API
+
+// Cache references to native implementation in case they are modified later
+var performance = global.performance;
+var nativeGetEntries = performance && performance.getEntries;
+
+// Is the User Timing API natively supported?
+var isNativeSupported = (typeof nativeGetEntries === 'function');
+
+/**
+ *  Native Implementation
+ *  Uses the native-supported performance.getEntries function
+ */
+function nativeImplementation () {
+  return nativeGetEntries.call(performance);
+}
+
+/**
+ *  Polyfill Implementation
+ *  Manually provides similar functionality to native performance.getEntries
+ *  using an in-memory array of timeline events
+ */
+function polyfillImplementation () {
+  return timeline;
+}
+
+module.exports = {
+  getEntries: function () {
+    var func = (isNativeSupported ? nativeImplementation : polyfillImplementation);
+    return func();
+  }
+};

package/lib/performance/getEntriesByName.js

@@ -0,0 +1,61 @@
+/**
+ *  @fileOverview
+ *  Performance.getEntriesByName uses the native User Timing API
+ *  when available and falls back to a manual implementation if not
+ */
+
+// Imports
+var global = require('../global');
+var perfGetEntries = require('./getEntries').getEntries;
+
+// Determine now (once) if we can use the native User Timing API
+
+// Cache references to native implementation in case they are modified later
+var performance = global.performance;
+var nativeGetEntriesByName = performance && performance.getEntriesByName;
+
+// Is the User Timing API natively supported?
+var isNativeSupported = (typeof nativeGetEntriesByName === 'function');
+
+/**
+ *  Native Implementation
+ *  Uses the native-supported performance.getEntriesByName function
+ */
+function nativeImplementation (name, entryType) {
+  return nativeGetEntriesByName.call(performance, name, entryType);
+}
+
+/**
+ *  Polyfill Implementation
+ *  Manually provides similar functionality to native
+ *  performance.getEntriesByName using a filter operation on
+ *  a list of all performance marks
+ */
+function polyfillImplementation (name, entryType) {
+  if (arguments.length === 0) {
+    throw new TypeError('Failed to execute \'getEntriesByName\' on \'Performance\': 1 argument required, but only 0 present.');
+  }
+
+  return perfGetEntries().filter(function (entry) {
+    if (entry.name === name) {
+      if (typeof entryType === 'undefined' || entry.entryType === entryType) {
+        return entry;
+      }
+    }
+  });
+}
+
+module.exports = {
+  /**
+   *  @param {String} name - The name of the mark to filter for
+   *  @param {String} [entryType] - The entryType of the mark to filter for
+   */
+  getEntriesByName: function (name, entryType) {
+    // Note: because the implementation functions explicitly check their number of arguments,
+    // we want to preserve the calls exactly as they came in
+   
+    var hasArguments = (arguments.length > 0);
+    var func = (isNativeSupported ? nativeImplementation : polyfillImplementation);
+    return (hasArguments ? func(name, entryType) : func());
+  }
+};

package/lib/performance/getEntriesByType.js

@@ -0,0 +1,55 @@
+/**
+ *  @fileOverview
+ *  Performance.getEntriesByType uses the native User Timing API
+ *  when available and falls back to a manual implementation if not
+ */
+
+// Imports
+var global = require('../global');
+var perfGetEntries = require('./getEntries').getEntries;
+
+// Determine now (once) if we can use the native User Timing API
+
+// Cache references to native implementation in case they are modified later
+var performance = global.performance;
+var nativeGetEntriesByType = performance && performance.getEntriesByType;
+
+// Is the User Timing API natively supported?
+var isNativeSupported = (typeof nativeGetEntriesByType === 'function');
+
+/**
+ *  Native Implementation
+ *  Uses the native-supported performance.getEntriesByType function
+ */
+function nativeImplementation (entryType) {
+  return nativeGetEntriesByType.call(performance, entryType);
+}
+
+/**
+ *  Polyfill Implementation
+ *  Manually provides similar functionality to native
+ *  performance.getEntriesByType using a filter operation on
+ *  a list of all performance marks
+ */
+function polyfillImplementation (entryType) {
+  if (arguments.length === 0) {
+    throw new TypeError('Failed to execute \'getEntriesByType\' on \'Performance\': 1 argument required, but only 0 present.');
+  }
+
+  return perfGetEntries().filter(function (entry) {
+    return entry.entryType === entryType;
+  });
+}
+
+module.exports = {
+  /**
+   *  @param {String} [entryType] - The entryType of the mark to filter for
+   */
+  getEntriesByType: function (entryType) {
+    // Note: because the implementation functions explicitly check their number of arguments,
+    // we want to preserve the calls exactly as they came in
+    var hasArguments = (arguments.length > 0);
+    var func = (isNativeSupported ? nativeImplementation : polyfillImplementation);
+    return (hasArguments ? func(entryType) : func());
+  }
+};

package/lib/performance/index.js

@@ -0,0 +1,11 @@
+/**
+ *  @fileOverview
+ *  Groups Performance sub-modules to keep them clean and testable
+ */
+
+module.exports.getEntries = require('./getEntries.js').getEntries;
+module.exports.getEntriesByName = require('./getEntriesByName.js').getEntriesByName;
+module.exports.getEntriesByType = require('./getEntriesByType.js').getEntriesByType;
+module.exports.now = require('./now.js').now;
+module.exports.mark = require('./mark.js').mark;
+module.exports.measure = require('./measure.js').measure;

package/lib/performance/mark.js

@@ -0,0 +1,97 @@
+/**
+ *  @fileOverview
+ *  Performance.mark uses the native User Timing API
+ *  when available and falls back to a manual implementation if not
+ */
+
+// Imports
+var global = require('../global');
+var perfNow = require('./now.js');
+var timeline = require('./entries').timeline;
+
+// Determine now (once) if we can use the native User Timing API
+
+// Cache references to native implementation in case they are modified later
+var performance = global.performance;
+var nativeMark = performance && performance.mark;
+
+// Is the User Timing API natively supported?
+var isNativeSupported = (typeof nativeMark === 'function');
+
+// Per http://www.w3.org/TR/user-timing/#extensions-performance-interface,
+// the mark name cannot be any of the attributes in the PerformanceTiming
+// interface: http://www.w3.org/TR/navigation-timing/#performancetiming.
+var reservedNames = {
+  navigationStart: 1,
+  unloadEventStart: 1,
+  unloadEventEnd: 1,
+  redirectStart: 1,
+  redirectEnd: 1,
+  fetchStart: 1,
+  domainLookupStart: 1,
+  domainLookupEnd: 1,
+  connectStart: 1,
+  connectEnd: 1,
+  secureConnectionStart: 1,
+  requestStart: 1,
+  responseStart: 1,
+  responseEnd: 1,
+  domLoading: 1,
+  domInteractive: 1,
+  domContentLoadedEventStart: 1,
+  domContentLoadedEventEnd: 1,
+  domComplete: 1,
+  loadEventStart: 1,
+  loadEventEnd: 1
+};
+
+/**
+ *  Native Implementation
+ *  Uses the native-supported performance.mark function
+ */
+function nativeImplementation (name) {
+  return nativeMark.call(performance, name);
+}
+
+/**
+ *  Polyfill Implementation
+ *  Manually provides similar functionality to native performance.mark
+ *  using a marks list and an array of timeline events
+ */
+function polyfillImplementation (name) {
+  // Validation: a mark name must be provided
+  if (arguments.length < 1) {
+    throw new SyntaxError('Cannot set mark without a name');
+  }
+
+  // Validation: the mark name cannot be one of the reserved names
+  if (name in reservedNames) {
+    throw new SyntaxError('Cannot set mark with reserved name "' + name + '"');
+  }
+
+  // Validation passed, can proceed
+
+  // Create the record
+  var record = {
+    entryType: 'mark',
+    name: name,
+    startTime: perfNow.now(),
+    duration: 0
+  };
+
+  // Push the record to the timeline
+  timeline.push(record);
+}
+
+module.exports = {
+  /**
+   *  @param {String} name - The name of the mark to create
+   */
+  mark: function (name) {
+    // Note: because the implementation functions explicitly check their number of arguments,
+    // we want to preserve the calls exactly as they came in
+    var hasArguments = (arguments.length > 0);
+    var func = (isNativeSupported) ? nativeImplementation : polyfillImplementation;
+    return (hasArguments) ? func(name) : func();
+  }
+};

package/lib/performance/measure.js

@@ -0,0 +1,106 @@
+/**
+ *  @fileOverview
+ *  Performance.measure uses the native User Timing API
+ *  when available and falls back to a manual implementation if not
+ */
+
+// Imports
+var global = require('../global');
+var perfNow = require('./now.js').now;
+var perfGetEntriesByType = require('./getEntriesByType').getEntriesByType;
+var timeline = require('./entries').timeline;
+
+// Determine now (once) if we can use the native User Timing API
+
+// Cache references to native implementation in case they are modified later
+var performance = global.performance;
+var nativeMeasure = performance && performance.measure;
+
+// Is the User Timing API natively supported?
+var isNativeSupported = (typeof nativeMeasure === 'function');
+
+/**
+ *  Native Implementation
+ *  Uses the native-supported performance.measure function
+ */
+function nativeImplementation (name, startMark, endMark) {
+  if (startMark === undefined) {
+    return nativeMeasure.call(performance, name);
+  }
+  else if (endMark === undefined) {
+    return nativeMeasure.call(performance, name, startMark);
+  }
+
+  return nativeMeasure.call(performance, name, startMark, endMark);
+}
+
+/**
+ *  Polyfill Implementation
+ *  Manually provides similar functionality to native performance.measure
+ *  using a measures list and an array of timeline events
+ */
+function polyfillImplementation (name, startMark, endMark) {
+  // Validation: a measure name must be provided
+  if (arguments.length < 1) {
+    throw new TypeError('Failed to execute \'measure\' on \'Performance\': 1 argument required, but only 0 present.');
+  }
+
+  var marks = perfGetEntriesByType('mark');
+  var filteredMarks;
+
+  /**
+   * If no startMark was passed, use navigationStart (0) as the startTime
+   * per the spec. If no endTime was passed, use performance.now() as the
+   * endTime. Otherwise, use the most recent mark(s) with the specified
+   * name being passed as startMark and endMark.
+   */
+  var startTime = 0;
+  var endTime = perfNow();
+
+  if (startMark !== undefined) {
+    filteredMarks = marks.filter(function (entry) {
+      return entry.entryName === startMark;
+    });
+    if (!filteredMarks.length) {
+      throw new Error('Failed to execute \'measure\' on \'Performance\': The mark \'' + startMark + '\' does not exist.');
+    }
+
+    // use the most recent mark with the matching name
+    startTime = filteredMarks[filteredMarks.length-1].startTime;
+  }
+
+  if (endMark !== undefined) {
+    filteredMarks = marks.filter(function (entry) {
+      return entry.entryName === endMark;
+    });
+    if (!filteredMarks.length) {
+      throw new Error('Failed to execute \'measure\' on \'Performance\': The mark \'' + endMark + '\' does not exist.');
+    }
+    // use the most recent mark with the matching name
+    endTime = filteredMarks[filteredMarks.length-1].startTime;
+  }
+
+  // Create the record
+  var record = {
+    entryType: 'measure',
+    name: name,
+    startTime: startTime,
+    duration: endTime - startTime
+  };
+
+  // Push the record to the timeline
+  timeline.push(record);
+}
+
+module.exports = {
+  /**
+   *  @param {String} name - The name of the measure to create
+   */
+  measure: function (name, startMark, endMark) {
+    // Note: because the implementation functions explicitly check their number of arguments,
+    // we want to preserve the calls exactly as they came in
+    var hasArguments = (arguments.length > 0);
+    var func = (isNativeSupported) ? nativeImplementation : polyfillImplementation;
+    return (hasArguments) ? func(name, startMark, endMark) : func();
+  }
+};

package/lib/performance/now.js

@@ -0,0 +1,63 @@
+/**
+ *  @fileOverview Provides a cross-browser safe way to use the Navigation Timing API
+ *  Ported from Firebird's scout directory
+ *  Based on https://gist.github.com/paulirish/5438650
+ *
+ *  Note: this is not a true polyfill in browsers that do not implement the
+ *  Navigation Timing API.  Rather than returning the time elapsed since
+ *  `navigationStart`, it will return the time elapsed since the polyfill was
+ *  installed.
+ *
+ *  Further reading:
+ *  http://www.w3.org/TR/user-timing/
+ *  http://caniuse.com/#search=User%20Timing
+ *  http://caniuse.com/#search=performance.now
+ *  http://caniuse.com/#search=Navigation%20Timing
+ */
+
+// Imports
+var global = require('../global');
+var dateNow = require('../date.now');
+
+// Cache references for speed and to guard against shenanigans
+var performance = global.performance;
+var nativeNow = performance && performance.now;
+
+// Is the Navigation Timing API natively supported?
+var isNativeSupported = (typeof nativeNow === 'function');
+
+// Used by the polyfill implementation to get the moment the module was installed
+var nowOffset = dateNow.now();
+
+// Use navigationStart as the offset when possible
+if (performance &&
+  performance.timing &&
+  typeof performance.timing.navigationStart === 'number'
+) {
+  // Use navigationStart value instead
+  nowOffset = performance.timing.navigationStart;
+}
+
+/**
+ *  Native Implementation
+ *  Uses the natively-supported performance.now function
+ */
+function nativeImplementation () {
+  return nativeNow.call(performance);
+}
+
+/**
+ * Polyfill Implementation
+ * Provides similar functionality to performance.now but instead uses a default
+ * offset of the moment the polyfill was installed
+ */
+function polyfillImplementation () {
+  return dateNow.now() - nowOffset;
+}
+
+module.exports = {
+  now: function () {
+    var func = (isNativeSupported) ? nativeImplementation : polyfillImplementation;
+    return func();
+  }
+};

package/lib/pixelsDisplayed/README.md

@@ -0,0 +1,19 @@
+# pixelsDisplayed
+
+> A module for detecting whether an element is located within the viewport
+
+## Usage
+
+```js
+var bvUIPixelsDisplayed = require('bv-ui-core/lib/pixelsDisplayed');
+var pixelsDisplayedVertical = bvUIPixelsDisplayed.pixelsDisplayedVertical;
+var pixelsDisplayedHorizontal = bvUIPixelsDisplayed.pixelsDisplayedHorizontal;
+
+
+if (pixelsDisplayedVertical(element) > 0) {
+  // element is vertically within viewport
+  if (pixelsDisplayedHorizontal(element) > 0) {
+    // element is both vertically and horizontally within viewport
+  }
+}
+```