@angular-wave/angular.ts 0.0.67 → 0.0.69

package/src/core/location/location.md

@@ -0,0 +1,114 @@
+/\*\*
+
+- The $location service parses the URL in the browser address bar (based on the
+- [window.location](https://developer.mozilla.org/en/window.location)) and makes the URL
+- available to your application. Changes to the URL in the address bar are reflected into
+- $location service and changes to $location are reflected into the browser address bar.
+-
+- **The $location service:**
+-
+- - Exposes the current URL in the browser address bar, so you can
+- - Watch and observe the URL.
+- - Change the URL.
+- - Synchronizes the URL with the browser when the user
+- - Changes the address bar.
+- - Clicks the back or forward button (or clicks a History link).
+- - Clicks on a link.
+- - Represents the URL object as a set of methods (protocol, host, port, path, search, hash).
+-
+- For more information see {@link guide/$location Developer Guide: Using $location}
+  \*/
+
+/\*\*
+
+- Use the `$locationProvider` to configure how the application deep linking paths are stored.
+  \*/
+
+/\*\*
+
+- @ngdoc event
+- @name $location#$locationChangeStart
+- @eventType broadcast on root scope
+- @description
+- Broadcasted before a URL will change.
+-
+- This change can be prevented by calling
+- `preventDefault` method of the event. See {@link ng.$rootScope.Scope#$on} for more
+- details about event object. Upon successful change
+- {@link ng.$location#$locationChangeSuccess $locationChangeSuccess} is fired.
+-
+- The `newState` and `oldState` parameters may be defined only in HTML5 mode and when
+- the browser supports the HTML5 History API.
+-
+- @param {Object} angularEvent Synthetic event object.
+- @param {string} newUrl New URL
+- @param {string=} oldUrl URL that was before it was changed.
+- @param {string=} newState New history state object
+- @param {string=} oldState History state object that was before it was changed.
+  \*/
+
+/\*\*
+
+- @ngdoc event
+- @name $location#$locationChangeSuccess
+- @eventType broadcast on root scope
+- @description
+- Broadcasted after a URL was changed.
+-
+- The `newState` and `oldState` parameters may be defined only in HTML5 mode and when
+- the browser supports the HTML5 History API.
+-
+- @param {Object} angularEvent Synthetic event object.
+- @param {string} newUrl New URL
+- @param {string=} oldUrl URL that was before it was changed.
+- @param {string=} newState New history state object
+- @param {string=} oldState History state object that was before it was changed.
+  \*/
+
+  /\*\*
+
+  - This method is getter / setter.
+  -
+  - Return search part (as object) of current URL when called without any parameter.
+  -
+  - Change search part when called with parameter and return `$location`.
+  -
+  -
+  - ```js
+
+    ```
+
+  - // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
+  - let searchObject = $location.search();
+  - // => {foo: 'bar', baz: 'xoxo'}
+  -
+  - // set foo to 'yipee'
+  - $location.search('foo', 'yipee');
+  - // $location.search() => {foo: 'yipee', baz: 'xoxo'}
+  - ```
+
+    ```
+
+  -
+  - @param {string|Object} search New search params - string or hash object.
+  -
+  - When called with a single argument the method acts as a setter, setting the `search` component
+  - of `$location` to the specified value.
+  -
+  - If the argument is a hash object containing an array of values, these values will be encoded
+  - as duplicate search parameters in the URL.
+  -
+  - @param {(string|Number|Array<string>|boolean)=} paramValue If `search` is a string or number, then `paramValue`
+  - will override only a single search property.
+  -
+  - If `paramValue` is an array, it will override the property of the `search` component of
+  - `$location` specified via the first argument.
+  -
+  - If `paramValue` is `null`, the property specified via the first argument will be deleted.
+  -
+  - If `paramValue` is `true`, the property specified via the first argument will be added with no
+  - value nor trailing equal sign.
+  -
+  - @return {Object} If called with no arguments returns the parsed `search` object. If called with
+  - one or more arguments returns `$location` object itself.
+    \*/

package/src/core/location/location.spec.js

@@ -2,10 +2,9 @@ import {
   LocationHtml5Url,
   LocationHashbangUrl,
   $LocationProvider,
-  LocationHashbangInHtml5Url,
 } from "./location";
 import { Angular } from "../../loader";
-import { createInjector } from "../../core/di/injector";
+import { createInjector } from "../di/injector";
 
 describe("$location", () => {
   let module;
@@ -464,6 +463,7 @@ describe("$location", () => {
           .hash("abcd")
           .state({ a: 2 })
           .search("bar", "baz");
+
         expect(locationUrl.path()).toEqual("/foo");
         expect(locationUrl.state()).toEqual({ a: 2 });
         expect(locationUrl.search() && locationUrl.search().bar).toBe("baz");
@@ -3310,81 +3310,6 @@ describe("$location", () => {
     });
   });
 
-  describe("LocationHashbangInHtml5Url", () => {
-    /* global LocationHashbangInHtml5Url: false */
-    let locationUrl;
-    let locationIndexUrl;
-
-    beforeEach(() => {
-      locationUrl = new LocationHashbangInHtml5Url(
-        "http://server/pre/",
-        "http://server/pre/",
-        "#!",
-      );
-      locationIndexUrl = new LocationHashbangInHtml5Url(
-        "http://server/pre/index.html",
-        "http://server/pre/",
-        "#!",
-      );
-    });
-
-    it("should rewrite URL", () => {
-      expect(parseLinkAndReturn(locationUrl, "http://other")).toEqual(
-        undefined,
-      );
-      expect(parseLinkAndReturn(locationUrl, "http://server/pre")).toEqual(
-        "http://server/pre/#!",
-      );
-      expect(parseLinkAndReturn(locationUrl, "http://server/pre/")).toEqual(
-        "http://server/pre/#!",
-      );
-      expect(
-        parseLinkAndReturn(locationUrl, "http://server/pre/otherPath"),
-      ).toEqual("http://server/pre/#!/otherPath");
-      // Note: relies on the previous state!
-      expect(
-        parseLinkAndReturn(locationUrl, "someIgnoredAbsoluteHref", "#test"),
-      ).toEqual("http://server/pre/#!/otherPath#test");
-
-      expect(parseLinkAndReturn(locationIndexUrl, "http://server/pre")).toEqual(
-        "http://server/pre/index.html#!",
-      );
-      expect(
-        parseLinkAndReturn(locationIndexUrl, "http://server/pre/"),
-      ).toEqual(undefined);
-      expect(
-        parseLinkAndReturn(locationIndexUrl, "http://server/pre/otherPath"),
-      ).toEqual("http://server/pre/index.html#!/otherPath");
-      // Note: relies on the previous state!
-      expect(
-        parseLinkAndReturn(
-          locationIndexUrl,
-          "someIgnoredAbsoluteHref",
-          "#test",
-        ),
-      ).toEqual("http://server/pre/index.html#!/otherPath#test");
-    });
-
-    it("should throw on url(urlString, stateObject)", () => {
-      expectThrowOnStateChange(locationUrl);
-    });
-
-    // it("should not throw when base path is another domain", () => {
-    //   initService({ html5Mode: true, hashPrefix: "!", supportHistory: true });
-    //   inject(
-    //     initBrowser({
-    //       url: "http://domain.com/base/",
-    //       basePath: "http://otherdomain.com/base/",
-    //     }),
-    //     ($location) => {
-    //       expect(() => {
-    //         $location.absUrl();
-    //       }).not.toThrow();
-    //     },
-    //   );
-    // });
-  });
-
   // function mockUpBrowser(options) {
   //   module(($windowProvider, $browserProvider) => {
   //     let browser;

package/src/core/parser/lexer.spec.js

@@ -1,6 +1,6 @@
 import { Lexer } from "./lexer";
 import { Angular } from "../../loader";
-import { createInjector } from "../../core/di/injector";
+import { createInjector } from "../di/injector";
 
 describe("lexer", () => {
   let $rootScope;

package/src/core/parser/parse.spec.js

@@ -7,7 +7,7 @@ import {
   valueFn,
   extend,
 } from "../../shared/utils";
-import { createInjector } from "../../core/di/injector";
+import { createInjector } from "../di/injector";
 import { ASTType } from "./ast-type";
 import { Angular } from "../../loader";
 

package/src/core/q/q.js

@@ -1,49 +1,44 @@
+import {
+  forEach,
+  minErr,
+  isUndefined,
+  isFunction,
+  isObject,
+  isDefined,
+  isError,
+  toDebugString,
+  isPromiseLike,
+} from "../../shared/utils";
+
 /**
  * @template T
- * @typedef {Object} angular.QPromise
+ * @typedef {Object} QPromise
  * @property {function(
  *   ((value: T) => (PromiseLike<never>|PromiseLike<T>|T))|null,
  *   ((reason: any) => (PromiseLike<never>|PromiseLike<T>|T))|null,
  *   ((state: any) => any)
- * ): angular.QPromise<T|never>} then - Calls one of the success or error callbacks asynchronously as soon as the result is available.
+ * ): QPromise<T|never>} then - Calls one of the success or error callbacks asynchronously as soon as the result is available.
  * @property {function(
- *   ((value: T) => (angular.QPromise<never>|angular.QPromise<T>|T))|null,
- *   ((reason: any) => (angular.QPromise<never>|angular.QPromise<never>|never))|null,
+ *   ((value: T) => (QPromise<never>|QPromise<T>|T))|null,
+ *   ((reason: any) => (QPromise<never>|QPromise<never>|never))|null,
  *   ((state: any) => any)
- * ): angular.QPromise<T|never>} then - Calls one of the success or error callbacks asynchronously as soon as the result is available.
- * @property {function(((reason: any) => (PromiseLike<never>|PromiseLike<T>|T))|null): angular.QPromise<T>|T} catch - Shorthand for promise.then(null, errorCallback).
- * @property {function(((reason: any) => (angular.QPromise<never>|angular.QPromise<T>|T))|null): angular.QPromise<T>|T} catch - Shorthand for promise.then(null, errorCallback).
- * @property {function(function(): void): angular.QPromise<T>} finally - Allows you to observe either the fulfillment or rejection of a promise, but to do so without modifying the final value.
+ * ): QPromise<T|never>} then - Calls one of the success or error callbacks asynchronously as soon as the result is available.
+ * @property {function(((reason: any) => (PromiseLike<never>|PromiseLike<T>|T))|null): QPromise<T>|T} catch - Shorthand for promise.then(null, errorCallback).
+ * @property {function(((reason: any) => (QPromise<never>|QPromise<T>|T))|null): QPromise<T>|T} catch - Shorthand for promise.then(null, errorCallback).
+ * @property {function(function(): void): QPromise<T>} finally - Allows you to observe either the fulfillment or rejection of a promise, but to do so without modifying the final value.
+ * @property {number} [$$intervalId] - Internal id set by the $interval service for callback notifications
+ * @property {number} [$$timeoutId] - Timeout id set by the $timeout service for cancelations
  */
 
 /**
  *@template T
- * @typedef {Object} angular.Deferred
- * @property {function(T|angular.QPromise<T>): void} resolve - Resolves the promise with a value or another promise.
+ * @typedef {Object} Deferred
+ * @property {function(T|QPromise<T>): void} resolve - Resolves the promise with a value or another promise.
  * @property {function(any): void} reject - Rejects the promise with a reason.
  * @property {function(any): void} notify - Provides a progress notification.
- * @property {angular.QPromise<T>} promise - The promise associated with this deferred object.
+ * @property {QPromise<T>} promise - The promise associated with this deferred object.
  */
 
-import {
-  forEach,
-  minErr,
-  isUndefined,
-  isFunction,
-  isObject,
-  isDefined,
-  isError,
-  toDebugString,
-  isPromiseLike,
-} from "../../shared/utils";
-
-/**
- * @ngdoc provider
- * @name $qProvider
- *
- *
- * @description
- */
 export function $QProvider() {
   let errorOnUnhandledRejections = true;
   this.$get = [
@@ -51,14 +46,16 @@ export function $QProvider() {
     "$exceptionHandler",
     /**
      *
-     * @param {*} $rootScope
+     * @param {import('../scope/scope').Scope} $rootScope
      * @param {import('../exception-handler').ErrorHandler} $exceptionHandler
      * @returns
      */
     function ($rootScope, $exceptionHandler) {
       return qFactory(
         (callback) => {
-          $rootScope.$evalAsync(callback);
+          $rootScope.$evalAsync(
+            /** @type {function(function):any} */ (callback),
+          );
         },
         $exceptionHandler,
         errorOnUnhandledRejections,
@@ -129,11 +126,6 @@ function qFactory(nextTick, exceptionHandler, errorOnUnhandledRejections) {
   const checkQueue = [];
 
   /**
-   * @ngdoc method
-   * @name ng.$q#defer
-   * @kind function
-   *
-   * @description
    * Creates a `Deferred` object which represents a task which will finish in the future.
    *
    * @returns {Deferred} Returns a new instance of deferred.
@@ -156,38 +148,45 @@ function qFactory(nextTick, exceptionHandler, errorOnUnhandledRejections) {
     };
   }
 
-  function QPromise() {
-    this.$$state = { status: 0 };
-  }
-
-  QPromise.prototype.then = function (onFulfilled, onRejected, progressBack) {
-    if (
-      isUndefined(onFulfilled) &&
-      isUndefined(onRejected) &&
-      isUndefined(progressBack)
-    ) {
-      return this;
+  class QPromise {
+    constructor() {
+      this.$$state = { status: 0 };
     }
-    const result = new QPromise();
-
-    this.$$state.pending = this.$$state.pending || [];
-    this.$$state.pending.push([result, onFulfilled, onRejected, progressBack]);
-    if (this.$$state.status > 0) scheduleProcessQueue(this.$$state);
 
-    return result;
-  };
+    then(onFulfilled, onRejected, progressBack) {
+      if (
+        isUndefined(onFulfilled) &&
+        isUndefined(onRejected) &&
+        isUndefined(progressBack)
+      ) {
+        return this;
+      }
+      const result = new QPromise();
+
+      this.$$state.pending = this.$$state.pending || [];
+      this.$$state.pending.push([
+        result,
+        onFulfilled,
+        onRejected,
+        progressBack,
+      ]);
+      if (this.$$state.status > 0) scheduleProcessQueue(this.$$state);
+
+      return result;
+    }
 
-  QPromise.prototype.catch = function (callback) {
-    return this.then(null, callback);
-  };
+    catch(callback) {
+      return this.then(null, callback);
+    }
 
-  QPromise.prototype.finally = function (callback, progressBack) {
-    return this.then(
-      (value) => handleCallback(value, resolve, callback),
-      (error) => handleCallback(error, reject, callback),
-      progressBack,
-    );
-  };
+    finally(callback, progressBack) {
+      return this.then(
+        (value) => handleCallback(value, resolve, callback),
+        (error) => handleCallback(error, reject, callback),
+        progressBack,
+      );
+    }
+  }
 
   function processQueue(state) {
     let fn;

package/src/core/q/q.spec.js

@@ -1,4 +1,4 @@
-import { createInjector } from "../../core/di/injector";
+import { createInjector } from "../di/injector";
 import { Angular } from "../../loader";
 
 /**

package/src/core/sce/sce.js

@@ -46,9 +46,7 @@ export const SCE_CONTEXTS = {
 // http://docs.closure-library.googlecode.com/git/local_closure_goog_string_string.js.source.html#line1021
 // Prereq: s is a string.
 export function escapeForRegexp(s) {
-  return s
-    .replace(/([-()[\]{}+?*.$^|,:#<!\\])/g, "\\$1")
-    .replace(/\x08/g, "\\x08");
+  return s.replace(/([-()[\]{}+?*.$^|,:#<!\\])/g, "\\$1");
 }
 
 export function adjustMatcher(matcher) {

package/src/core/scope/scope.js

@@ -392,7 +392,7 @@ export class Scope {
  *
  *    - `string`: Evaluated as {@link guide/expression expression}
  *    - `function(scope)`: called with current `scope` as a parameter.
- * @param {WatchListener} listener
+ * @param {WatchListener} [listener]
  * @param {boolean=} [objectEquality=false] Compare for object equality using {@link angular.equals} instead of
  *     comparing for reference equality.
  * @returns {function()} Returns a deregistration function for this listener.
@@ -415,7 +415,7 @@ export class Scope {
 
     lastDirtyWatch = null;
 
-    if (this.$$watchers.length == 0) {
+    if (this.$$watchers.length === 0) {
       this.$$digestWatchIndex = -1;
     }
     // we use unshift since we use a while loop in $digest for speed.
@@ -1155,7 +1155,7 @@ export class Scope {
    * will be scheduled. However, it is encouraged to always call code that changes the model
    * from within an `$apply` call. That includes code evaluated via `$evalAsync`.
    *
-   * @param {(string|function())=} expr An AngularTS expression to be executed.
+   * @param {(string|function(any):any)=} expr An AngularTS expression to be executed.
    *
    *    - `string`: execute using the rules as defined in {@link guide/expression expression}.
    *    - `function(scope)`: execute the function with the current `scope` parameter.
@@ -1187,9 +1187,6 @@ export class Scope {
     return id;
   }
 
-  /**
-   * @private
-   */
   $$postDigest(fn) {
     $$postDigestQueue.push(fn);
   }

package/src/core/timeout/timeout.js

@@ -1,5 +1,5 @@
 import { markQExceptionHandled } from "../q/q";
-import { isDefined, isFunction, minErr, sliceArgs } from "../../shared/utils";
+import { isDefined, minErr, sliceArgs } from "../../shared/utils";
 
 const $timeoutMinErr = minErr("$timeout");
 
@@ -23,22 +23,16 @@ export function $TimeoutProvider() {
       const deferreds = {};
 
       /**
-       * @ngdoc service
-       * @name $timeout
-       *
-       * @description
+    
        * AngularJS's wrapper for `window.setTimeout`. The `fn` function is wrapped into a try/catch
        * block and delegates any exceptions to
-       * {@link ng.$exceptionHandler $exceptionHandler} service.
+       * {@link $exceptionHandler} service.
        *
        * The return value of calling `$timeout` is a promise, which will be resolved when
        * the delay has passed and the timeout function, if provided, is executed.
        *
        * To cancel a timeout request, call `$timeout.cancel(promise)`.
        *
-       * In tests you can use {@link ngMock.$timeout `$timeout.flush()`} to
-       * synchronously flush the queue of deferred functions.
-       *
        * If you only want a promise that will be resolved after some specified delay
        * then you can call `$timeout` without the `fn` function.
        *
@@ -46,17 +40,11 @@ export function $TimeoutProvider() {
        * @param {number=} [delay=0] Delay in milliseconds.
        * @param {boolean=} [invokeApply=true] If set to `false` skips model dirty checking, otherwise
        *   will invoke `fn` within the {@link ng.$rootScope.Scope#$apply $apply} block.
-       * @returns {Promise} Promise that will be resolved when the timeout is reached. The promise
+       * @returns {import("../q/q").QPromise<any>} Promise that will be resolved when the timeout is reached. The promise
        *   will be resolved with the return value of the `fn` function.
        *
        */
       function timeout(fn, delay, invokeApply = true) {
-        if (!isFunction(fn)) {
-          invokeApply = delay;
-          delay = fn;
-          fn = () => {};
-        }
-
         const args = sliceArgs(arguments, 3);
         const skipApply = isDefined(invokeApply) && !invokeApply;
         const deferred = (skipApply ? $$q : $q).defer();
@@ -87,14 +75,10 @@ export function $TimeoutProvider() {
       }
 
       /**
-       * @ngdoc method
-       * @name $timeout#cancel
-       *
-       * @description
        * Cancels a task associated with the `promise`. As a result of this, the promise will be
        * resolved with a rejection.
        *
-       * @param {Promise=} promise Promise returned by the `$timeout` function.
+       * @param {import("../q/q").QPromise<any>} promise Promise returned by the `$timeout` function.
        * @returns {boolean} Returns `true` if the task hasn't executed yet and was successfully
        *   canceled.
        */

package/src/core/url-utils/url-utils.js

@@ -1,5 +1,10 @@
 import { isString } from "../../shared/utils";
 
+/**
+ * HTTP protocol
+ * @typedef {"http"|"https"} HttpProtocol
+ */
+
 // service.
 const urlParsingNode = window.document.createElement("a");
 const originUrl = urlResolve(window.location.href);

package/src/directive/attrs/boolean.spec.js

@@ -1,6 +1,6 @@
 import { Angular } from "../../loader";
 import { createInjector } from "../../core/di/injector";
-import { dealoc, JQLite } from "../../shared/jqlite/jqlite";
+import { dealoc } from "../../shared/jqlite/jqlite";
 
 describe("boolean attr directives", () => {
   let element, $rootScope, $compile, $rootElement;

package/src/directive/bind/bind.js

@@ -37,8 +37,8 @@ export const ngBindHtmlDirective = [
     return {
       restrict: "A",
       compile: (_tElement, tAttrs) => {
-        var ngBindHtmlGetter = $parse(tAttrs.ngBindHtml);
-        var ngBindHtmlWatch = $parse(tAttrs.ngBindHtml, (val) => val);
+        const ngBindHtmlGetter = $parse(tAttrs.ngBindHtml);
+        const ngBindHtmlWatch = $parse(tAttrs.ngBindHtml, (val) => val);
         return (scope, element) => {
           scope.$watch(ngBindHtmlWatch, () => {
             // The watched value is the unwrapped value. To avoid re-escaping, use the direct getter.

package/src/directive/class/class.js

@@ -2,7 +2,7 @@ import { forEach, isObject, isString } from "../../shared/utils";
 
 function classDirective(name, selector) {
   name = `ngClass${name}`;
-  var indexWatchExpression;
+  let indexWatchExpression;
 
   return [
     "$parse",

package/src/directive/form/form.js

@@ -153,12 +153,6 @@ FormController.prototype = {
   },
 
   /**
-   * @ngdoc method
-   * @name form.FormController#$addControl
-   * @param {object} control control object, either a {@link form.FormController} or an
-   * {@link ngModel.NgModelController}
-   *
-   * @description
    * Register a control with the form. Input elements using ngModelController do this automatically
    * when they are linked.
    *
@@ -187,11 +181,6 @@ FormController.prototype = {
   },
 
   /**
-   * @ngdoc method
-   * @name form.FormController#$getControls
-   * @returns {Array} the controls that are currently part of this form
-   *
-   * @description
    * This method returns a **shallow copy** of the controls that are currently part of this form.
    * The controls can be instances of {@link form.FormController `FormController`}
    * ({@link ngForm "child-forms"}) and of {@link ngModel.NgModelController `NgModelController`}.
@@ -222,12 +211,6 @@ FormController.prototype = {
   },
 
   /**
-   * @ngdoc method
-   * @name form.FormController#$removeControl
-   * @param {object} control control object, either a {@link form.FormController} or an
-   * {@link ngModel.NgModelController}
-   *
-   * @description
    * Deregister a control from the form.
    *
    * Input elements using ngModelController do this automatically when they are destroyed.
@@ -382,7 +365,7 @@ FormController.prototype = {
  *        (undefined),  or skipped (null). Pending is used for unfulfilled `$asyncValidators`.
  *        Skipped is used by AngularJS when validators do not run because of parse errors and when
  *        `$asyncValidators` do not run because any of the `$validators` failed.
- * @param {NgModelController | FormController} controller - The controller whose validity state is
+ * @param {import("../model/model").NgModelController | FormController} controller - The controller whose validity state is
  *        triggering the change.
  */
 addSetValidityMethod({

package/src/directive/form/form.spec.js

@@ -1,7 +1,7 @@
 import { Angular } from "../../loader";
 import { createInjector } from "../../core/di/injector";
 import { dealoc, JQLite } from "../../shared/jqlite/jqlite";
-import { FormController } from "../../directive/form/form";
+import { FormController } from "./form";
 
 describe("form", () => {
   let doc;
@@ -679,7 +679,7 @@ describe("form", () => {
       $compile(doc)(scope);
       scope.$apply();
 
-      var parent = scope.parent,
+      const parent = scope.parent,
         child = scope.child;
 
       expect(parent).toBeDefined();

package/src/directive/include/include.js

@@ -7,6 +7,13 @@ export const ngIncludeDirective = [
   "$templateRequest",
   "$anchorScroll",
   "$animate",
+  /**
+   *
+   * @param {*} $templateRequest
+   * @param {import("../../services/anchor-scroll").AnchorScrollFunction} $anchorScroll
+   * @param {*} $animate
+   * @returns
+   */
   ($templateRequest, $anchorScroll, $animate) => ({
     restrict: "ECA",
     priority: 400,

package/src/directive/input/input.js

@@ -203,7 +203,7 @@ export function weekParser(isoWeek, existingDate) {
 
   function getFirstThursdayOfYear(year) {
     // 0 = index of January
-    var dayOfWeekOnFirst = new Date(year, 0, 1).getDay();
+    const dayOfWeekOnFirst = new Date(year, 0, 1).getDay();
     // 4 = index of Thursday (+1 to account for 1st = 5)
     // 11 = index of *next* Thursday (+1 account for 1st = 12)
     return new Date(