Build latest production builds

dist/foresight.js

@@ -100,6 +100,13 @@ return /******/ (function(modules) { // webpackBootstrap
 
 "use strict";
 
+/*!
+ * Foresight
+ *
+ * @author James Ooi <james.ooi@forefront.com.my>
+ * @license MIT
+ * @copyright 2018 (c) FOREFRONT International Sdn Bhd
+ */
 var __assign = (this && this.__assign) || function () {
     __assign = Object.assign || function(t) {
         for (var s, i = 1, n = arguments.length; i < n; i++) {
@@ -113,12 +120,30 @@ var __assign = (this && this.__assign) || function () {
 };
 __webpack_require__(1);
 var Utils = __webpack_require__(2);
-var Foresight = (function () {
+/**
+ * Foresight is an analytics library that allows for declarative event tracking
+ * in your websites.
+ * @class
+ */
+var Foresight = /** @class */ (function () {
+    /**
+     * @constructor
+     */
     function Foresight(config) {
         var _this = this;
+        /**
+         * Stores a mapping of elements with is respective functions to de-register
+         * listeners.
+         * @private
+         */
         this._untrackFns = new Map();
+        /**
+         * Stores an instance of an IntersectionObserver.
+         * @private
+         */
         this._observer = null;
         this.options = __assign({}, Foresight.defaultOptions, config);
+        // Initialise IntersectionObserver
         this._observer = new IntersectionObserver(function (entries, observer) {
             entries.forEach(function (entry) {
                 if (entry.isIntersecting) {
@@ -127,7 +152,14 @@ var Foresight = (function () {
                 }
             });
         }, this.options.observerOptions);
+        // Start tracking
+        if (!this.options.defer) {
+            this.start();
+        }
     }
+    /**
+     * Start event tracking for all DOM elements with event tracking attributes.
+     */
     Foresight.prototype.start = function (root) {
         var _this = this;
         if (root === void 0) { root = document.body; }
@@ -138,16 +170,21 @@ var Foresight = (function () {
             .toArray(root.querySelectorAll('[data-track], [data-track-view]'))
             .map(function (element) { return _this.track(element); });
     };
+    /**
+     * Enables event tracking for a DOM element with event tracking attribute.
+     */
     Foresight.prototype.track = function (element) {
         if (!this._untrackFns.has(element)) {
             this._untrackFns.set(element, { click: null, view: null });
         }
         var untrackFn = this._untrackFns.get(element);
+        // Track clicks
         if (element.getAttribute('data-track') !== null) {
             if (untrackFn.click == null) {
                 untrackFn.click = this._trackClicks(element);
             }
         }
+        // Track views
         if (element.getAttribute('data-track-view') !== null) {
             if (untrackFn.view == null) {
                 untrackFn.view = this._trackViews(element);
@@ -155,6 +192,9 @@ var Foresight = (function () {
         }
         this._untrackFns.set(element, untrackFn);
     };
+    /**
+     * Disable event tracking for a DOM element.
+     */
     Foresight.prototype.untrack = function (element) {
         var untrackFn = this._untrackFns.get(element);
         if (untrackFn === undefined) {
@@ -168,17 +208,30 @@ var Foresight = (function () {
         }
         this._untrackFns.delete(element);
     };
+    /**
+     * Parse an event string and returns a `EventData` object.
+     * @private
+     */
     Foresight.prototype._parseEventString = function (eventString) {
         var split = eventString.split(';');
         var category = split[0], action = split[1], label = split[2];
+        // If only one argument is provided, then the argument is the action
         if (split.length === 1) {
             action = category;
             category = undefined;
         }
         return { category: category, action: action, label: label, interaction: true };
     };
+    /**
+     * Registers click listeners that triggers an analytics event when the element
+     * is clicked or middle clicked.
+     *
+     * @returns Returns a function to remove the event listener.
+     * @private
+     */
     Foresight.prototype._trackClicks = function (element) {
         var _this = this;
+        // Define listen fucntion
         var listener = function (e) {
             _this._onTrackedClick(element, e);
         };
@@ -189,6 +242,13 @@ var Foresight = (function () {
             element.removeEventListener('auxclick', listener);
         };
     };
+    /**
+     * Registers a view observer that triggers an analytics event when the element
+     * is in view.
+     *
+     * @returns Returns a function that disconnects the view observer.
+     * @private
+     */
     Foresight.prototype._trackViews = function (element) {
         var _this = this;
         this._observer.observe(element);
@@ -196,10 +256,14 @@ var Foresight = (function () {
             _this._observer.unobserve(element);
         };
     };
+    /**
+     * Handles a click event on an element that is being tracked by Foresight.
+     * @private
+     */
     Foresight.prototype._onTrackedClick = function (element, event) {
         var s = element.getAttribute('data-track');
         var data = this._parseEventString(s);
-        data.interaction = !this.options.nonInteractionClicks;
+        data.interaction = this.options.clicksAreInteractions;
         if (element.getAttribute('data-track:non-interaction') !== null) {
             data.interaction = false;
         }
@@ -209,10 +273,14 @@ var Foresight = (function () {
             'non_interaction': !data.interaction,
         });
     };
+    /**
+     * Handles a view event on an element that is being tracked by Foresight.
+     * @private
+     */
     Foresight.prototype._onTrackedView = function (element, observer) {
         var s = element.getAttribute('data-track-view');
         var data = this._parseEventString(s);
-        data.interaction = !this.options.nonInteractionViews;
+        data.interaction = this.options.viewsAreInteractions;
         if (element.getAttribute('data-track-view:interaction') !== null) {
             data.interaction = true;
         }
@@ -222,9 +290,14 @@ var Foresight = (function () {
             'non_interaction': !data.interaction,
         });
     };
+    /**
+     * Default Options
+     * @static
+     */
     Foresight.defaultOptions = {
-        nonInteractionClicks: false,
-        nonInteractionViews: true,
+        defer: false,
+        clicksAreInteractions: true,
+        viewsAreInteractions: false,
         observerOptions: {},
     };
     return Foresight;
@@ -980,6 +1053,9 @@ exports.toArray = toArray_1.default;
 "use strict";
 
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Creates a new `Array` instance from an array-like or iterable object.
+ */
 function toArray(arrayLike) {
     return [].slice.call(arrayLike);
 }

typings/foresight.d.ts

+/*!
+ * Foresight
+ *
+ * @author James Ooi <james.ooi@forefront.com.my>
+ * @license MIT
+ * @copyright 2018 (c) FOREFRONT International Sdn Bhd
+ */
 import 'intersection-observer';
+/**
+ * Available options for configuring Foresight.
+ */
 interface ForesightConfig {
+    /** Defer tracking initialisation. */
+    defer?: boolean;
+    /** Configure the intersection observer. */
     observerOptions?: IntersectionObserverInit;
-    nonInteractionClicks?: boolean;
-    nonInteractionViews?: boolean;
+    /** Treat clicks as an interactive event. Defaults to true. */
+    clicksAreInteractions?: boolean;
+    /** Treat views as an interactive event. Defaults to false. */
+    viewsAreInteractions?: boolean;
 }
+/**
+ * Foresight is an analytics library that allows for declarative event tracking
+ * in your websites.
+ * @class
+ */
 declare class Foresight {
+    /**
+     * Default Options
+     * @static
+     */
     static defaultOptions: Partial<ForesightConfig>;
+    /**
+     * Stores the options of the current Foresight instance.
+     * @public
+     */
     options: ForesightConfig;
+    /**
+     * Stores a mapping of elements with is respective functions to de-register
+     * listeners.
+     * @private
+     */
     private _untrackFns;
+    /**
+     * Stores an instance of an IntersectionObserver.
+     * @private
+     */
     private _observer;
+    /**
+     * @constructor
+     */
     constructor(config: ForesightConfig);
+    /**
+     * Start event tracking for all DOM elements with event tracking attributes.
+     */
     start(root?: Element): void;
+    /**
+     * Enables event tracking for a DOM element with event tracking attribute.
+     */
     track(element: Element): void;
+    /**
+     * Disable event tracking for a DOM element.
+     */
     untrack(element: Element): void;
+    /**
+     * Parse an event string and returns a `EventData` object.
+     * @private
+     */
     private _parseEventString;
+    /**
+     * Registers click listeners that triggers an analytics event when the element
+     * is clicked or middle clicked.
+     *
+     * @returns Returns a function to remove the event listener.
+     * @private
+     */
     private _trackClicks;
+    /**
+     * Registers a view observer that triggers an analytics event when the element
+     * is in view.
+     *
+     * @returns Returns a function that disconnects the view observer.
+     * @private
+     */
     private _trackViews;
+    /**
+     * Handles a click event on an element that is being tracked by Foresight.
+     * @private
+     */
     private _onTrackedClick;
+    /**
+     * Handles a view event on an element that is being tracked by Foresight.
+     * @private
+     */
     private _onTrackedView;
 }
 export = Foresight;

typings/utils/toArray.d.ts

+/**
+ * Creates a new `Array` instance from an array-like or iterable object.
+ */
 export default function toArray<T>(arrayLike: any): T[];