bv-ui-core 0.1.1

package/lib/region/README.md

@@ -0,0 +1,64 @@
+# Region
+
+The `region` module is a module meant to standardize the detection of various
+regions, such as EU or APAC. It exposes functions that can test if a locale
+belongs to various regions. It can also simply lookup the region for a given
+locale.
+
+So far, the only region supported is EU, but the module is designed to be
+easily extendable when the need to support other regions pops up.
+
+## Usage Examples
+
+Loading the root module:
+```javascript
+var region = require('bv-ui-core/lib/region');
+
+region.hasLocale('europe', 'en_US'); // false
+region.hasLocale('europe', 'en_GB'); // true
+
+region.hasTerritory('europe', 'US'); // false
+region.hasTerritory('europe', 'GB'); // true
+
+region.lookupTerritory('US'); // unsupported
+region.lookupTerritory('GB'); // europe
+
+region.lookupLocale('en_US'); // unsupported
+region.lookupLocale('en_GB'); // europe
+
+```
+This can be useful when you'll have to support detection of multiple regions.
+As only the EU region is supported for now, it's not particularly useful yet.
+
+Loading a specific region module:
+```javascript
+var europe = require('bv-ui-core/lib/region/europe');
+
+europe.hasLocale('en_US'); // false
+europe.hasLocale('en_GB'); // true
+
+europe.hasTerritory('US'); // false
+europe.hasTerritory('GB'); // true
+
+// Get an Array with all the region's country codes.
+var europeanTerritories = europe.listTerritories();
+
+// If you prefer a map, you can require it directly.
+var europeanTerritoryMap = require('bv-ui-core/lib/region/europe/territories');
+```
+This can be useful if you've no need for other regions and would like to shave
+every last byte from your client-side code.
+
+Errors will be thrown if invalid locale or territory codes are provided. This
+is to protect the user against mistaking language codes for territory codes.
+For example, 'fr' is the code for the French language, and 'FR' is the code
+for France. To avoid the case where `region.hasTerritory('europe', 'fr');`
+returns false, we throw an error.
+
+```javascript
+var region = require('bv-ui-core/lib/region');
+
+// The user likely meant to check 'FR'. To avoid confusion, we throw an error
+// instead of just returning false.
+region.hasTerritory('europe', 'fr');
+```

package/lib/region/europe/index.js

@@ -0,0 +1,94 @@
+/**
+ * @module Module for determining if a locale is in the EU.
+ *
+ * Examples:
+ *
+ * // Example 1, loading this module directly:
+ * var europe = require('bv-ui-core/lib/region/europe');
+ * europe.hasLocale('en_US'); // false
+ * europe.hasLocale('en_GB'); // true
+ *
+ * europe.hasTerritory('US'); // false
+ * europe.hasTerritory('GB'); // true
+ *
+ * // Example 2, loading the region module:
+ * var region = require('bv-ui-core/lib/region');
+ * region.hasLocale('europe', 'en_US'); // false
+ * region.hasLocale('europe', 'en_GB'); // true
+ *
+ * region.hasTerritory('europe', 'US'); // false
+ * region.hasTerritory('europe', 'GB'); // true
+ *
+ * Errors will be thrown if an invalid locale or territory code is provided.
+ *
+ * Example 3, providing invalid input:
+ * var europe = require('bv-ui-core/lib/region/europe');
+ * europe.hasLocale('banana'); // throws an error
+ *
+ * // 'fr' is a language code. The correct French territory code is 'FR'.
+ * europe.hasTerritory('fr'); // throws an error.
+ */
+
+// territories is a map that contains an entry for each valid EU country
+// code, so territories[territory] will return either true or undefined.
+// We just need to coerce that into a boolean value and we're good to go.
+var territories = require('./territories');
+
+// Some constant patterns for valid values.
+var VALID_TERRITORY = /^[A-Z]{2}$/;
+var VALID_LOCALE = /^[a-z]{2}[_-][A-Z]{2}$/;
+
+module.exports = {
+
+  /**
+   * Determine if a given territory is an EU territory.
+   *
+   * @param {String} territory - The locale to be tested. This function accepts
+   *   territory codes of the XX format. Three letter territory codes are not
+   *   (yet) supported.
+   *
+   * @return {Boolean} Returns true if the territory is an EU territory.
+   *   Returns false otherwise.
+   *
+   * @throws
+   */
+  hasTerritory: function (territory) {
+
+    if (!VALID_TERRITORY.test(territory)) {
+      throw new Error('Invalid territory code passed to hasTerritory.');
+    }
+
+    return !!territories[territory];
+  },
+
+  /**
+   * Determine if a given locale is an EU locale based on the territory code.
+   *
+   * @param {String} locale - The locale to be tested. This function accepts
+   *   locales of the xx_XX format only.
+   *
+   * @return {Boolean} Returns true if the locale is an EU territory.
+   *   Returns false otherwise.
+   *
+   * @throws
+   */
+  hasLocale: function (locale) {
+
+    if (!VALID_LOCALE.test(locale)) {
+      throw new Error('Invalid locale code passed to hasLocale.');
+    }
+
+    var territory = locale.split(/[\_\-]/).pop();
+
+    return !!territories[territory];
+  },
+
+  /**
+   * Return a list of country codes in this region.
+   *
+   * @return {Array} - A list of country codes in the european region.
+   */
+  listTerritories: function () {
+    return Object.keys(territories);
+  }
+};

package/lib/region/europe/territories.js

@@ -0,0 +1,40 @@
+/**
+ * @file List of country codes legally considered part of the EU region.
+ */
+
+var countryCodes = {
+  AT: true, // Austria
+  BE: true, // Belgium
+  BG: true, // Bulgaria
+  CH: true, // Switzerland
+  CY: true, // Republic of Cyprus
+  CZ: true, // Czech Republic
+  DE: true, // Germany
+  DK: true, // Denmark
+  ES: true, // Spain
+  EE: true, // Estonia
+  FI: true, // Finland
+  FR: true, // France
+  GB: true, // Great Britain / UK
+  GR: true, // Greece
+  HR: true, // Croatia
+  HU: true, // Hungary
+  IE: true, // Ireland
+  IS: true, // Iceland
+  IT: true, // Italy
+  LI: true, // Liechtenstein
+  LT: true, // Lithuania
+  LU: true, // Luxembourg
+  LV: true, // Latvia
+  MT: true, // Malta
+  NL: true, // Netherlands
+  NO: true, // Norway
+  PL: true, // Poland
+  PT: true, // Portugal
+  RO: true, // Romania
+  SE: true, // Sweden
+  SI: true, // Slovenia
+  SK: true  // Slovakia
+};
+
+module.exports = countryCodes;

package/lib/region/index.js

@@ -0,0 +1,123 @@
+/**
+ * @module Used to determine if a given locale is part of a given region.
+ *
+ * Currently, the only supported region is EU, because it's the only region
+ * we have a need to support. However, this module was designed so that it'd
+ * be easy to add new regions, such as APAC, NA, LA, etc.
+ *
+ * This module is the "generic" module, and can be used to detect any region
+ * we support. If your project only needs to detect a specific region, you can
+ * require that region's module on its own to reduce file size.
+ *
+ * Examples:
+ *
+ * var region = require('bv-ui-core/lib/region');
+ * region.hasLocale('europe', 'en_US'); // false
+ * region.hasLocale('europe', 'en_GB'); // true
+ *
+ * region.hasTerritory('europe', 'US'); // false
+ * region.hasTerritory('europe', 'GB'); // true
+ *
+ * Errors will be thrown if an invalid locale or territory code is provided.
+ *
+ * Example 3, providing invalid input:
+ * var region = require('bv-ui-core/lib/region');
+ * region.hasLocale('europe', 'banana'); // throws an error
+ *
+ * // 'fr' is a language code. The correct French territory code is 'FR'.
+ * region.hasTerritory('europe', 'fr'); // throws an error.
+ */
+
+var regions = {
+  europe: require('./europe')
+};
+
+module.exports = {
+
+  /**
+   * Determine if a given territory is an EU territory.
+   *
+   * @param {String} region - The region to check for the territory in.
+   *
+   * @param {String} territory - The locale to be tested. This function accepts
+   *   territory codes of the XX format. Three letter territory codes are not
+   *   (yet) supported.
+   *
+   * @return {Boolean} Returns true if the territory is an EU territory.
+   *   Returns false otherwise.
+   */
+  hasTerritory: function (region, territory) {
+
+    if (!regions[region]) {
+      throw new Error('Invalid region passed to region.hasTerritory');
+    }
+
+    // Simply wrap around the individual region modules.
+    return regions[region].hasTerritory(territory);
+  },
+
+  /**
+   * Determine if a given locale is an EU locale based on the territory code.
+   *
+   * @param {String} region - The region to check for the territory in.
+   *
+   * @param {String} locale - The locale to be tested. This function accepts
+   *   locales of the xx_XX format only.
+   *
+   * @return {Boolean} Returns true if the locale is an EU territory.
+   *   Returns false otherwise.
+   */
+  hasLocale: function (region, locale) {
+
+    if (!regions[region]) {
+      throw new Error('Invalid region passed to region.hasLocale');
+    }
+
+    // Simply wrap around the individual region modules.
+    return regions[region].hasLocale(locale);
+  },
+
+  /**
+   * Return the region of a specified territory.
+   *
+   * @param {String} territory - The name of the territory.
+   *
+   * @return {String} Returns the name of the region, or 'unsupported' if the
+   *   territory is not part of a supported region.
+   */
+  lookupTerritory: function (territory) {
+
+    // Loop through the regions looking for the territory.
+    var region;
+    for (region in regions) {
+      if (regions[region].hasTerritory(territory)) {
+        return region;
+      }
+    }
+
+    // If we get here, the territory isn't in any currently supported region.
+    return 'unsupported';
+  },
+
+  /**
+   * Return the region of a specified locale.
+   *
+   * @param {String} locale - The name of the locale.
+   *
+   * @return {String} Returns the name of the region, or 'unsupported' if the
+   *   locale is not part of a supported region.
+   */
+  lookupLocale: function (locale) {
+
+    // Loop through the regions looking for the locale.
+    var region;
+    for (region in regions) {
+      if (regions[region].hasLocale(locale)) {
+        return region;
+      }
+    }
+
+    // If we get here, the locale isn't in any currently supported region.
+    return 'unsupported';
+  }
+};

package/lib/staticAssetLoader/README.md

@@ -0,0 +1,116 @@
+# Static Asset Loader
+
+This can be used by client-side web applications to request and receive the
+static resources they require from a suitable static asset server. The
+primary objective is to allow multiple discrete web applications on the same
+page to converge on shared dependencies. Each dependency is only loaded
+once and this reduces the overall page footprint.
+
+## Basic Usage
+
+### Configuration
+
+The static asset loader must be configured with the following:
+
+  * A function to generate asset URLs from asset name and version strings.
+  * The name of the application namespace.
+
+Applications sharing static assets must use the same namespace.
+
+```javascript
+var staticAssetLoaderFactory = require('bv-ui-core/lib/staticAssetLoader');
+
+var staticAssetLoader = staticAssetLoaderFactory.create({
+  /**
+   * Convert one or more asset strings into a static asset service URL.
+   *
+   * The details depend on the static asset server capabilities. This is an
+   * example implementation for a server capable of delivering asset bundles.
+   *
+   * @param {String[]} An array of asset names and version: ['jQuery@2.0.0'].
+   * @return {String} The URL for the asset.
+   */
+  generateUrl: function (assetNames, namespaceName) {
+    var filename = encodeURIComponent(assetNames.slice(0).sort().join('+')) + '.js';
+
+    namespaceName = encodeURIComponent(namespaceName);
+    return 'https://static.example.com/1/asset/' + namespaceName + '/' + filename;
+  },
+
+  /**
+   * Provide the name of a namespace to hold the _staticAssetRegistry properties
+   * and methods. Applications sharing static assets must use the same
+   * namespace.
+   */
+  namespaceName: 'EXAMPLE'
+});
+```
+
+### Require Assets
+
+When the application requires a resource of a supported type, use the client to
+request that resource via the `require` method.
+
+```javascript
+// Request the desired assets. For example:
+staticAssetLoader.require([
+  'underscore@1.0.0',
+  'jquery-custom@1.11.1',
+  'backbone@1.2.0'
+], function (_, $, Backbone) {
+  // This callback will be invoked when all of the required assets have been
+  // resolved.
+});
+```
+
+Note that when requesting an asset that has dependency assets - for example,
+Backbone depends on jQuery and either Underscore or Lodash - it is necessary to
+request those dependencies in the same `require` call.
+
+### Define Assets
+
+Applications that ship with resources that might be useful to other applications
+on the page can provide those resources via the static asset loader. This again
+allows for a convergence of dependencies and reduced page weight.
+
+```javascript
+// After definition, staticAssetLoader.require('jquery-custom@1.11.1', callback)
+// will call back immediately with the provided instance of jQuery.
+staticAssetLoader.define('jquery-custom@1.11.1', jQuery);
+```
+
+### Order and Timing of Calls
+
+Calls to `require` and `define` can be made in any order and at any time, for so
+long as each call to `require` includes all needed dependency assets. Obviously
+it is usually better to make these calls as early as possible in the application
+initialization process so as to minimize lead time.
+
+## Form of the Static Asset Service
+
+The static assert service is a web service that can respond to requests such as:
+
+`https://static.example.com/1/asset/namespace/jquery@1.11.1.js`
+
+Importantly, the static asset service must be capable of serving bundles of
+assets in response to a single request, with the assets listed in alphabetical
+order. E.g.:
+
+`https://static.example.com/1/asset/namespace/backbone@1.2.0+jquery@1.11.1.js`
+
+The returned Javascript must both define the assets themselves and then provide
+the asset to the static asset client in the same way as described above. For
+example:
+
+```javascript
+(function (define) {
+
+  // Asset source code goes here.
+  //
+  // ...
+
+  // Then provide the asset or assets to the client.
+  define('asset@1.0.0', asset);
+
+}(window[namespace]._staticAssetRegistry.define));
+```

package/lib/staticAssetLoader/index.js

@@ -0,0 +1,248 @@
+/**
+ * @fileOverview
+ * A static asset loader to pull resources at particular versions from a static
+ * asset service. This could be as simple as an S3-backed CDN, or a webserver
+ * serving from a directory of files. E.g. a server that can respond to requests
+ * such as:
+ *
+ * https://static.example.com/1/asset/jquery@1.11.1.js
+ *
+ * Importantly, the static asset service must be capable of serving bundles of
+ * assets in a single request, where these assets are listed in alphabetical
+ * order. E.g.:
+ *
+ * https://static.example.com/1/asset/backbone@1.2.0+jquery@1.11.1.js
+ *
+ * This is primarily intended to reduce asset duplication among multiple
+ * distinct client applications running on the same page.
+ *
+ * The returned Javascript must both define the assets themselves and then
+ * provide the asset to the static asset client. For example:
+ *
+ * (function (define) {
+ *
+ *   // Asset source code goes here.
+ *   //
+ *   // ...
+ *
+ *   // Then provide the asset or assets to the client.
+ *   define('asset@1.0.0', ['dependency@1.0.0'], asset);
+ *
+ * }(window[namespace]._staticAssetRegistry.define));
+ */
+
+var loader = require('../loader');
+var namespacer = require('../namespacer');
+
+/**
+ * Invoke the provided function on each element of the array.
+ *
+ * @param {Array} arr An array.
+ * @param {Function} fn Function to invoke as fn(element, index, array).
+ */
+function forEach (arr, fn) {
+  if (!arr || !arr.length) {
+    return;
+  }
+
+  for (var index = 0; index < arr.length; index++) {
+    fn(arr[index], index, arr);
+  }
+}
+
+/**
+ * Create a new array containing the results of applying the provided function
+ * to each element.
+ *
+ * @param {Array} arr An array.
+ * @param {Function} fn Function to invoke as fn(element, index, array).
+ * @return {Array} The mapped array.
+ */
+function map (arr, fn) {
+  var mappedArray = [];
+
+  forEach(arr, function (val, index, originalArray) {
+    mappedArray.push(fn(val, index, originalArray));
+  });
+
+  return mappedArray;
+}
+
+module.exports = {
+  /**
+   * A factory function for static asset loaders.
+   *
+   * See the documentation for the properties required for the configuration
+   * object.
+   *
+   * @param {Object} config Configuration.
+   * @return {Object} A static asset loader instance.
+   */
+  create: function staticAssetLoaderFactory (config) {
+    var generateUrl = config.generateUrl;
+    var namespaceName = config.namespaceName;
+
+    if (!namespaceName) {
+      throw new Error('Cannot initialize staticAssetLoader without a namespace name.');
+    }
+
+    if (typeof generateUrl !== 'function') {
+      throw new Error('Cannot initialize staticAssetLoader without a URL generation function.');
+    }
+
+    var loaderOptions = config.loaderOptions || {};
+    var NS = namespacer.namespace(namespaceName);
+    var registry = NS._staticAssetRegistry = NS._staticAssetRegistry || {
+      // Stores defined entities by asset name. E.g.:
+      //
+      // {
+      //   'jquery@1.11.1': jquery,
+      //   ...
+      // }
+      assets: {},
+      // Stores requests indexed by included asset, each of which can specify
+      // multiple assets. Has the form:
+      //
+      // {
+      //   'jquery@1.11.1': {
+      //     assetNames: ['jquery@1.11.1', ...],
+      //     callback: function (jQuery, ...),
+      //     complete: false
+      //   },
+      //   ...
+      // }
+      requests: {},
+      // Set below to the _define function, so that loaded asset wrappers can
+      // use it to define assets.
+      define: undefined
+    };
+
+    /**
+     * Given a request object, call back with the list of requested assets, in
+     * the same order as requested, if all assets are defined and the callback
+     * has not already occurred.
+     *
+     * @param {Object} request
+     */
+    function callbackIfComplete (request) {
+      // Already called back?
+      if (request.complete) {
+        return;
+      }
+
+      var complete = true;
+      var assets = map(request.assetNames, function (assetName) {
+        var asset = registry.assets[assetName];
+
+        if (!asset) {
+          complete = false;
+        }
+
+        return asset;
+      });
+
+      if (complete) {
+        request.complete = true;
+        if (typeof request.callback === 'function') {
+          request.callback.apply(null, assets);
+        }
+      }
+    }
+
+    /**
+     * Define assets. Usage is:
+     *
+     * _define('x@1.0.0', x);
+     *
+     * Later calls to _require() for this asset name will yield the defined
+     * asset.
+     *
+     * Any currently pending calls to _require() now satisfied will resolve.
+     *
+     * @param {String} assetName The name of the asset. E.g. 'jquery@1.11.1'.
+     * @param {Mixed} asset The asset.
+     */
+    function _define (assetName, asset) {
+      // Ignore an attempt to redefine an asset. This can cause potentially
+      // interesting problems when some references point to instance A and
+      // others to instance B.
+      if (registry.assets[assetName]) {
+        return;
+      }
+
+      registry.assets[assetName] = asset;
+      forEach(registry.requests[assetName], callbackIfComplete);
+    }
+
+    /**
+     * Require assets and provide a callback to be invoked when the assets are
+     * resolved.
+     *
+     * @param {String[]} assetNames An array of supported asset names.
+     * @param {Function} callback The callback to be called when the assets are
+     *   resolved, with the assets as its arguments in the same order as the
+     *   provided assets array.
+     */
+    function _require (assetNames, callback) {
+      var request = {
+        assetNames: assetNames,
+        callback: callback,
+        complete: false
+      };
+
+      forEach(assetNames, function (assetName) {
+        registry.requests[assetName] = registry.requests[assetName] || [];
+        registry.requests[assetName].push(request);
+      });
+
+      // Are all the dependencies already in place, and so we can skip the
+      // loading of assets?
+      callbackIfComplete(request);
+      if (request.complete) {
+        return;
+      }
+
+      var assetNamesToBeRequested = [];
+
+      forEach(assetNames, function (assetName) {
+        // The asset already exists.
+        if (registry.assets[assetName]) {
+          return;
+        }
+        // There is already a pending request for this asset. So don't issue
+        // another request, just ensure that a response is delivered to this
+        // request when the pending request completes.
+        else if (registry.requests[assetName].length > 1) {
+          return;
+        }
+        // There is no pending request; we need to queue it for requesting.
+        else {
+          assetNamesToBeRequested.push(assetName);
+        }
+      });
+
+      // If we queued any requests, now we need to make them.
+      if (assetNamesToBeRequested.length) {
+        loader.loadScript(
+          generateUrl(assetNamesToBeRequested, namespaceName),
+          loaderOptions,
+          function (error) {
+            if (error) {
+              throw new Error(
+                'Failed to load ' + assetNamesToBeRequested.join(', ') + ': ' + error.toString());
+            }
+          }
+        );
+      }
+    }
+
+    // This is made available for responses from the static asset server to use.
+    registry.define = _define;
+
+    // Return the static asset loader interface.
+    return {
+      require: _require,
+      define: _define
+    };
+  }
+};