docs(quickstart): quickstart revised with verbose mode toggle button

public/_includes/_util-fns.jade

@@ -46,7 +46,64 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
     else
       != styleString(jsonExtract, stylePatterns)
 
+- // Open (and close) an explanation <div>. See QuickStart
+script.
+  function why(id, backTo) {
+    var id = "#"+id;
+    var el = document.querySelector(id);
+    el.hidden=el.hidden=!el.hidden;
 
+    if (el.hidden && backTo){
+      // the next line is required to work around a bug in WebKit (Chrome / Safari)
+      location.href = "#";
+      location.href =  "#" + backTo;
+    }
+  }
+script.
+  function verbose(isVerbose) {
+    isVerbose = !! isVerbose;
+    var el = document.querySelector('button.verbose.off');
+    el.style.display = isVerbose ? 'block' : 'none';
+    var el = document.querySelector('button.verbose.on');
+    el.style.display = isVerbose ? 'none' : 'block';
+    
+    CCSStylesheetRuleStyle('main','.l-verbose-section', 'display',
+      isVerbose ? 'block' : 'none');
+  }
+
+script.
+  function CCSStylesheetRuleStyle(stylesheet, selectorText, style, value){
+    /* returns the value of the element style of the rule in the stylesheet
+    *  If no value is given, reads the value
+    *  If value is given, the value is changed and returned
+    *  If '' (empty string) is given, erases the value.
+    *  The browser will apply the default one
+    *
+    * string stylesheet: part of the .css name to be recognized, e.g. 'default'
+    * string selectorText: css selector, e.g. '#myId', '.myClass', 'thead td'
+    * string style: camelCase element style, e.g. 'fontSize'
+    * string value optional : the new value
+    */
+    var CCSstyle = undefined, rules, sheet;
+    for(var m in document.styleSheets){
+      sheet = document.styleSheets[m];
+      if(sheet.href && sheet.href.indexOf(stylesheet) != -1){
+      rules = sheet[document.all ? 'rules' : 'cssRules'];
+      for(var n in rules){
+        console.log(rules[n].selectorText);
+        if(rules[n].selectorText == selectorText){
+          CCSstyle = rules[n].style;
+          break;
+        }
+      }
+      break;
+      }
+    }
+    if(value == undefined)
+      return CCSstyle[style]
+    else
+      return CCSstyle[style] = value
+  }
 //---------------------------------------------------------------------------------------------------------
 - var translatePath = function(filePath, region) {
 -   filePath = filePath.trim();
@@ -134,6 +191,7 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
 -  return source;
 - }
 
+
 - var getFragFilePath = function (filePath, region) {
 -   filePath = filePath.trim();
 -   var extn = getExtn(filePath);

public/docs/_examples/quickstart/ts/index.html

@@ -36,7 +36,6 @@
             .then(null, console.error.bind(console));
     </script>
     <!-- #enddocregion systemjs -->
-
   </head>
 
   <!-- 3. Display the application -->
@@ -45,5 +44,4 @@
     <my-app>Loading...</my-app>
   </body>
   <!-- #enddocregion my-app -->
-
 </html>

public/docs/_examples/styles.css

@@ -81,7 +81,7 @@ nav a.router-link-active {
   left: .1em;
 }
 .items li.selected:hover {
-  background-color: #BBD8DC !important;
+  background-color: #BBD8DC;
   color: white;
 }
 .items .text {

public/docs/ts/latest/guide/_data.json

@@ -78,6 +78,11 @@
     "intro": "Angular 1 applications can be incrementally upgraded to Angular 2."
   },
 
+  "typescript-configuration": {
+    "title": "TypeScript Configuration",
+    "intro": "TypeScript configuration for Angular 2 developers"
+  },
+  
   "glossary": {
     "title": "Glossary",
     "intro": "Brief definitions of the most important words in the Angular 2 vocabulary"

public/docs/ts/latest/guide/typescript-configuration.jade

@@ -0,0 +1,151 @@
+include ../../../../_includes/_util-fns
+
+:marked
+  TypeScript is a primary language for Angular application development.
+  
+  TypeScript is a dialect of JavaScript with design-time support for type-safety and tooling.
+  
+  Browsers can't execute TypeScript directly. It has to be "transpiled" into JavaScript with the *tsc* compiler
+  and that effort requires some configuration.
+  
+  This chapter covers some aspects of TypeScript configuration and the TypeScript environment
+  that are important to Angular developers.
+
+a(id="tsconfig")
+.l-main-section
+:marked
+  ## *tsconfig.json*
+  We typically add a TypeScript configuration file (`tsconfig.json`) to our project to
+  guide the compiler as it generates JavaScript files.
+.l-sub-section
+  :marked
+    Get details about `tsconfig.json` from the official
+    [TypeScript wiki](https://github.com/Microsoft/TypeScript/wiki/tsconfig.json).
+:marked
+  We created the following `tsconfig.json` for the [QuickStart](../quickstart.html):
++makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")
+:marked
+  The options and flags in this file are essential for Angular 2 applications.
+  
+  <a id="noImplicitAny"></a>
+  ### *noImplicitAny* and *suppressImplicitAnyIndexErrors*
+
+  TypeScript developers disagree about whether the `noImplicitAny` flag should be `true` or `false`.
+  There is no correct answer and we can change the flag later.
+  But our choice now can make a difference in larger projects so it merits discussion.
+
+  When the `noImplicitAny` flag is `false` (the default),
+  the compiler silently defaults the type of a variable to `any` if it cannot infer
+  the type based on how the variable is used. That's what we mean by *implicit `any`*.
+
+  We initialized the `noImplicitAny` flag to `false` in the QuickStart 
+  to make learning TypeScript development easier.
+  
+  When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
+  the type, it still generates the JavaScript files. But it also **reports an error**.
+  Many seasoned developers prefer this stricter setting because type checking catches more
+  unintentional errors at compile time.
+  
+  We can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
+  We do so when that seems like the best choice for the situation, 
+  deliberately and explicitly, after giving the matter some thought.
+
+  If we set the `noImplicitAny` flag to `true`, we may get *implicit index errors* as well.
+  Most developers feel that *this particular error* is more annoying than helpful.
+  We can suppress them with the following additional flag.
+code-example(format=".").
+  "suppressImplicitAnyIndexErrors":true
+
+
+a(id="typings")
+.l-main-section
+:marked
+  ## TypeScript Typings
+  Many JavaScript libraries such as jQuery, the Jasmine testing library, and Angular itself,
+  extend the JavaScript environment with features and syntax
+  that the TypeScript compiler doesn't recognize natively.
+  When the compiler doesn't recognize something, it throws an error. 
+  
+  We use [TypeScript type definition files](http://www.typescriptlang.org/Handbook#writing-dts-files)
+  &mdash; *d.ts files* &mdash; to tell the compiler about the libraries we load.
+  
+  TypeScript-aware editors leverage these same definition files to display type information about library features.
+  
+  Many libraries include their definition files in their npm packages where both the TypeScript compiler and editors
+  can find them. Angular is one such library. 
+  Peek into the `node_modules/angular2/` folder of any Angular application to see several `...d.ts` files that describe parts of Angular.
+  
+  **We do nothing to get *typings* files for library packages with bundled *d.ts* files.**
+  
+  ### Manual typings
+  Sadly, many libraries &mdash; jQuery, Jasmine, and Lodash among them &mdash; do *not* include `d.ts` files in their npm packages.
+  Fortunately, either their authors or community contributors have created separate *d.ts* files for these libraries and 
+  published them in well-known locations.
+  The *typings* tool can find and fetch these files for us.
+  
+  We installed the [typings](https://github.com/typings/typings/blob/master/README.md) tool 
+  with npm (it's listed among the *devDependencies* in the `package.json`) and added an npm script
+  to run that tool automatically after *npm* installation completes.
++makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".")
+:marked
+  This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file 
+  such as this one from the [QuickStart](../quickstart.html):
++makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
+:marked
+  We identified only one *typings* file in the QuickStart, the *d.ts* file for 
+  [es6-shim](https://github.com/paulmillr/es6-shim/blob/master/README.md) that brings ES2015/ES6
+  capabilities to our ES5 browsers. 
+  QuickStart itself doesn't need this shim but many of the documentation samples do
+  and most of us would be disappointed if typical ES2015 features didn't work out-of-the-box.
+
+  We can also run the *typings* tool ourselves. The following command lists the locally installed typings files.
+code-example(format="").
+  npm run typings -- list
+:marked
+    The following command installs the typings file for the Jasmine test library and updates the `typings.config` 
+    so we that we get it automatically the next time.
+code-example(format="").
+  npm run typings -- install jasmine --ambient --save
+.l-sub-section
+  :marked
+    The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) is important; 
+    it tells npm to pass all arguments to the right of `--` to the *typings* command.
+    
+    Learn about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).
+:marked
+  #### Typing file collisions
+  
+  The TypeScript compiler does not tolerate redefinition of a type. For example, it throws an error if it's given two definitions for
+  the `Promise` type.
+  
+  Double definitions are common. In fact, the `typings` tool deliberately creates
+  duplicate sets of typings (for reasons best explained elsewhere). 
+  Look in the project structure for the *typings folder* where we should find something like:
+.filetree
+  .file typings
+  .children
+    .file browser
+    .children
+      .file ambient
+        .children
+          .file es6-shim
+          .children
+            .file es6-shim.d.ts
+  .children
+    .file main
+    .children
+      .file ambient
+        .children
+          .file es6-shim
+          .children
+            .file es6-shim.d.ts          
+  .children
+     .file browser.d.ts
+     .file main.d.ts
+:marked
+  The `es6-shim` typings are duplicated and the `browser.d.ts` and `main.d.ts` have overlapping content.
+  
+  We must tell the compiler to ignore one or the other. 
+  We removed the `main` set from consideration in the `exclude` section of our `tsconfig.json` file:
++makeJson('quickstart/ts/tsconfig.1.json', {paths: 'exclude'}, 'tsconfig.json (exclude)')(format=".")
+:marked

public/resources/css/layout/_layout.scss

@@ -139,7 +139,29 @@
   }
 }
 
+button.verbose {
+  font-size: ($unit * 3);
+  @media handheld and (max-width: $phone-breakpoint),
+  screen and (max-device-width: $phone-breakpoint),
+  screen and (max-width: $tablet-breakpoint) {
+    font-size: ($unit * 2);
+  }  
+}
+button.verbose.on {display: none}
 
+.l-verbose-section {
+  margin: 0px 0px ($unit * 4) 0px;
+  padding-left: ($unit * 2);  
+  //background: lighten($light, 5%);
+  border-left: ($unit / 6) solid $grey;
+  border-radius: ($unit / 6);
+}
+.l-verbose-inherit {
+  margin: 0;
+  padding: 0;
+  border-left: 0;
+  border-radius: 0;
+}
 
 /*
 * Margins & Padding