sync from upstream

.github/ISSUE_TEMPLATE.md

@@ -10,7 +10,7 @@
 #### What are the steps to reproduce?
 
 Providing a Plunker (or similar) is the *best* way to get the team to see your issue.
-Plunker template: http://plnkr.co/edit/o077B6uEiiIgkC0S06dd
+Plunker template: https://goo.gl/DlHd6U
 
 
 #### What is the use-case or motivation for changing an existing behavior?

.gitignore

@@ -4,6 +4,7 @@
 /dist
 /tmp
 /deploy
+/screenshots
 
 # dependencies
 /node_modules

.travis.yml

@@ -2,14 +2,13 @@ language: node_js
 sudo: false
 
 node_js:
-  - '6.9.1'
+  - '6.10.2'
 
 addons:
-  apt:
-    sources:
-      - ubuntu-toolchain-r-test
-    packages:
-      - libstdc++6
+  jwt:
+    # SAUCE_ACCESS_KEY<=secret for FIREBASE_ACCESS_TOKEN to work around travis-ci/travis-ci#7223, unencrypted value in valentine as FIREBASE_ACCESS_TOKEN>
+    # we alias FIREBASE_ACCESS_TOKEN to $SAUCE_ACCESS_KEY in env.sh and set the SAUCE_ACCESS_KEY there
+    - secure: "PKts/IbxuJRWWOEeiGbl8Z9zds0M+hIdCH/g/E4WbQ9yzSvSbdwzfmRfFccQFjxjsrY7+SJMVjsURZy+xUyBpzqgWYHUItnSVqjZb8DlyAU2IXyg8TM9BVLkGGe6k5k4PIFVmfMMMzQwWMM0X0W9w3oYmfHL5egxwSHvf9HIqLolLNXg8sqamIdS5d5KoCXf1c+oRjN/IMBktzNBR6N4OFOZQXVoepXNiIvTWAcTtOPBvFWdKP2n7RVioHKdm4a85aCUpDJp+LYGaLqiQZoRzmzfVTnAhTAPdd4ao5w/+jojrfZIHV55bqYF9rLnQMTneKsiyVNVYJzOLuxmARa/EEKfZld+J3rX4/o4cogrU38YSZF+T7J9g/7CTsnIZ3F6W6m+8iJbIBh55nGOQi5PVe458Q/nGb3fgQd2Z4+6lK9k479H4Ssh/Y7hbVQbepqEVIXzZKqWX6/ZE4iWoR/Q2dm0hySFmmB/R2etixX5JxhnHvgobTYIQ+1liJVp/3YFW1ru64Yg6yz/V291Bhh9g31znmTROCJ/usAmZZaLUqW1TDKnLIMP+M74MF9XERqcWKywXRFwxP4E5uDnx/vAyN49gL+SDfrBUxUtXrTkKZAlglwo9SgA7cOYEPWrionvKcGm87gCBYHFUmXZNQVzh212fpuJYXb/vy0sPDj8La4="
 
 branches:
   only:
@@ -19,30 +18,30 @@ env:
   global:
   - LOGS_DIR=/tmp/angular-material2-build/logs
   - SAUCE_USERNAME=angular-ci
-  - SAUCE_ACCESS_KEY=9b988f434ff8-fbca-8aa4-4ae3-35442987
   - BROWSER_STACK_USERNAME=angularteam1
   - BROWSER_STACK_ACCESS_KEY=BWCd4SynLzdDcv8xtzsB
-  - ARCH=linux-x64
   - BROWSER_PROVIDER_READY_FILE=/tmp/angular-material2-build/readyfile
   - BROWSER_PROVIDER_ERROR_FILE=/tmp/angular-material2-build/errorfile
-  # GITHUB_TOKEN_ANGULAR
-  - secure: "fq/U7VDMWO8O8SnAQkdbkoSe2X92PVqg4d044HmRYVmcf6YbO48+xeGJ8yOk0pCBwl3ISO4Q2ot0x546kxfiYBuHkZetlngZxZCtQiFT9kyId8ZKcYdXaIW9OVdw3Gh3tQyUwDucfkVhqcs52D6NZjyE2aWZ4/d1V4kWRO/LMgo="
+
   matrix:
     # Order: a slower build first, so that we don't occupy an idle travis worker waiting for others to complete.
     - MODE=lint
-    - MODE=extract_metadata
+    - MODE=aot
+    - MODE=closure-compiler
+    - MODE=payload
     - MODE=e2e
     - MODE=saucelabs_required
     - MODE=browserstack_required
-    - MODE=saucelabs_optional
-    - MODE=browserstack_optional
 
 matrix:
   fast_finish: true
   allow_failures:
   - env: "MODE=saucelabs_optional"
   - env: "MODE=browserstack_optional"
 
+before_install:
+  - source ./scripts/ci/env.sh
+
 install:
   - npm install
 

CODING_STANDARDS.md

@@ -12,11 +12,12 @@ ES6 or TypeScript.
 ### General
 
 #### Write useful comments
-Comments that explain what some block of code does are nice; they can tell you something in less time than it would take to follow through the code itself.
+Comments that explain what some block of code does are nice; they can tell you something in less
+time than it would take to follow through the code itself.
 
-Comments that explain why some block of code exists at all, or does something the way it does, 
-are _invaluable_. The "why" is difficult, or sometimes impossible, to track down without seeking out 
-the original author. When collaborators are in the same room, this hurts productivity. 
+Comments that explain why some block of code exists at all, or does something the way it does,
+are _invaluable_. The "why" is difficult, or sometimes impossible, to track down without seeking out
+the original author. When collaborators are in the same room, this hurts productivity.
 When collaborators are in different timezones, this can be devastating to productivity.
 
 For example, this is a not-very-useful comment:
@@ -37,13 +38,18 @@ if (!$attrs['tabindex']) {
 }
 ```
 
+In TypeScript code, use JsDoc-style comments for descriptions (on classes, members, etc.) and
+use `//` style comments for everything else (explanations, background info, etc.).
+
+In SCSS code, always use `//` style comments.
+
 #### Prefer more focused, granular components vs. complex, configurable components.
 
 For example, rather than doing this:
 ```html
 <md-button>Basic button</md-button>
-<md-button class="md-fab">FAB</md-button>
-<md-button class="md-icon-button">pony</md-button>
+<md-button class="mat-fab">FAB</md-button>
+<md-button class="mat-icon-button">pony</md-button>
 ```
 
 do this:
@@ -54,47 +60,195 @@ do this:
 ```
 
 #### Prefer small, focused modules
-Keeping modules to a single responsibility makes the code easier to test, consume, and maintain. 
-ES6 modules offer a straightforward way to organize code into logical, granular units. 
+Keeping modules to a single responsibility makes the code easier to test, consume, and maintain.
+ES6 modules offer a straightforward way to organize code into logical, granular units.
 Ideally, individual files are 200 - 300 lines of code.
 
+As a rule of thumb, once a file draws near 400 lines (barring abnormally long constants / comments),
+start considering how to refactor into smaller pieces.
+
 #### Less is more
-Once a feature is released, it never goes away. We should avoid adding features that don't offer 
-high user value for price we pay both in maintenance, complexity, and payload size. When in doubt, 
-leave it out. 
+Once a feature is released, it never goes away. We should avoid adding features that don't offer
+high user value for price we pay both in maintenance, complexity, and payload size. When in doubt,
+leave it out.
+
+This applies especially to providing two different APIs to accomplish the same thing. Always
+prefer sticking to a _single_ API for accomplishing something.
+
+### 100 column limit
+All code and docs in the repo should be 100 columns or fewer. This applies to TypeScript, SCSS,
+HTML, bash scripts, and markdown files.
+
+### API Design
+
+#### Boolean arguments
+Avoid adding boolean arguments to a method in cases where that argument means "do something extra".
+In these cases, prefer breaking the behavior up into different functions.
+
+```ts
+// AVOID
+function getTargetElement(createIfNotFound = false) {
+  // ...
+}
+```
 
-This applies especially so to providing two different APIs to accomplish the same thing. Always 
-prefer sticking to a _single_ API for accomplishing something. 
+```ts
+// PREFER
+function getExistingTargetElement() {
+  // ...
+}
+
+function createTargetElement() {
+ // ...
+}
+```
 
 ### TypeScript
 
-#### Provide function descriptions
-For functions that are more complicated than a simple getter/setter, provide at least a brief 
-sentence explaining what the function does and/or _why_ it does something.
+#### Typing
+Avoid `any` where possible. If you find yourself using `any`, consider whether a generic may be
+appropriate in your case.
+
+For methods and properties that are part of a component's public API, all types must be explicitly
+specified because our documentation tooling cannot currently infer types in places where TypeScript
+can.
+
+#### Fluent APIs
+When creating a fluent or builder-pattern style API, use the `this` return type for methods:
+```
+class ConfigBuilder {
+  withName(name: string): this {
+    this.config.name = name;
+    return this;
+  }
+}
+```
+
+#### Access modifiers
+* Omit the `public` keyword as it is the default behavior.
+* Use `private` when appropriate and possible, prefixing the name with an underscore.
+* Use `protected` when appropriate and possible with no prefix.
+* Prefix *library-internal* properties and methods with an underscore without using the `private`
+keyword. This is necessary for anything that must be public (to be used by Angular), but should not
+be part of the user-facing API. This typically applies to symbols used in template expressions,
+`@ViewChildren` / `@ContentChildren` properties, host bindings, and `@Input` / `@Output` properties
+(when using an alias).
+
+Additionally, the `@docs-private` JsDoc annotation can be used to hide any symbol from the public
+API docs.
+
+#### JsDoc comments
+
+All public APIs must have user-facing comments. These are extracted and shown in the documation
+on [material.angular.io](https://material.angular.io).
+
+Private and internal APIs should have JsDoc when they are not obvious. Ultimately it is the purview
+of the code reviewer as to what is "obvious", but the rule of thumb is that *most* classes,
+properties, and methods should have a JsDoc description.
+
+Properties should have a concise description of what the property means:
+```ts
+  /** The label position relative to the checkbox. Defaults to 'after' */
+  @Input() labelPosition: 'before' | 'after' = 'after';
+```
+
+Methods blocks should describe what the function does and provide a description for each parameter
+and the return value:
+```ts
+  /**
+   * Opens a modal dialog containing the given component.
+   * @param component Type of the component to load into the dialog.
+   * @param config Dialog configuration options.
+   * @returns Reference to the newly-opened dialog.
+   */
+  open<T>(component: ComponentType<T>, config?: MdDialogConfig): MdDialogRef<T> { ... }
+```
+
+Boolean properties and return values should use "Whether..." as opposed to "True if...":
+```ts
+  /** Whether the button is disabled. */
+  disabled: boolean = false;
+```
+
+#### Naming
+
+##### General
+* Prefer writing out words instead of using abbreviations.
+* Prefer *exact* names over short names (within reason). E.g., `labelPosition` is better than
+`align` because the former much more exactly communicates what the property means.
+* Except for `@Input` properties, use `is` and `has` prefixes for boolean properties / methods.
+
+##### Classes
+Classes should be named based on what they're responsible for. Names should capture what the code
+*does*, not how it is used:
+```
+/** NO: */
+class RadioService { }
+
+/** YES: */
+class UniqueSelectionDispatcher { }
+```
+
+Avoid suffixing a class with "Service", as it communicates nothing about what the class does. Try to
+think of the class name as a person's job title.
+
+Classes that correspond to a directive with an `md-` prefix should also be prefixed with `Md`.
+CDK classes should not have a prefix.
+
+##### Methods
+The name of a method should capture the action that is performed *by* that method rather than
+describing when the method will be called. For example,
+
+```ts
+/** AVOID: does not describe what the function does. */
+handleClick() {
+  // ...
+}
+
+/** PREFER: describes the action performed by the function. */
+activateRipple() {
+  // ...
+}
+```
+
+#### Inheritance
+
+Avoid using inheritence to apply reusable behaviors to multiple components. This limits how many
+behaviors can be composed.
+
+### Angular
+
+#### Host bindings
+Prefer using the `host` object in the directive configuration instead of `@HostBinding` and
+`@HostListener`. We do this because TypeScript preserves the type information of methods with
+decorators, and when one of the arguments for the method is a native `Event` type, this preserved
+type information can lead to runtime errors in non-browser environments (e.g., server-side
+pre-rendering).
+
 
 ### CSS
 
 #### Be cautious with use of `display: flex`
-* The [baseline calculation for flex elements](http://www.w3.org/TR/css-flexbox-1/#flex-baselines) 
-is different than other display values, making it difficult to align flex elements with standard 
+* The [baseline calculation for flex elements](http://www.w3.org/TR/css-flexbox-1/#flex-baselines)
+is different than other display values, making it difficult to align flex elements with standard
 elements like input and button.
 * Component outermost elements are never flex (block or inline-block)
 * Don't use `display: flex` on elements that will contain projected content.
 
 #### Use lowest specificity possible
-Always prioritize lower specificity over other factors. Most style definitions should consist of a 
-single element or css selector plus necessary state modifiers. Avoid SCSS nesting for the sake of 
-code organization. This will allow users to much more easily override styles.
+Always prioritize lower specificity over other factors. Most style definitions should consist of a
+single element or css selector plus necessary state modifiers. **Avoid SCSS nesting for the sake of
+code organization.** This will allow users to much more easily override styles.
 
 For example, rather than doing this:
 ```scss
-md-calendar {
+.mat-calendar {
   display: block;
 
-  .md-month {
+  .mat-month {
     display: inline-block;
 
-    .md-date.md-selected {
+    .mat-date.mat-selected {
       font-weight: bold;
     }
   }
@@ -103,15 +257,15 @@ md-calendar {
 
 do this:
 ```scss
-md-calendar {
+.mat-calendar {
   display: block;
 }
 
-.md-calendar-month {
+.mat-calendar-month {
   display: inline-block;
 }
 
-.md-calendar-date.md-selected {
+.mat-calendar-date.mat-selected {
   font-weight: bold;
 }
 ```
@@ -120,12 +274,12 @@ md-calendar {
 The end-user of a component should be the one to decide how much margin a component has around it.
 
 #### Prefer styling the host element vs. elements inside the template (where possible).
-This makes it easier to override styles when necessary. For example, rather than 
+This makes it easier to override styles when necessary. For example, rather than
 
 ```scss
-:host {
+the-host-element {
   // ...
-  
+
   .some-child-element {
     color: red;
   }
@@ -134,7 +288,7 @@ This makes it easier to override styles when necessary. For example, rather than
 
 you can write
 ```scss
-:host {
+the-host-element {
   // ...
   color: red;
 }
@@ -156,11 +310,11 @@ This is a low-effort task that makes a big difference for low-vision users. Exam
 When it is not super obvious, include a brief description of what a class represents. For example:
 ```scss
 // The calendar icon button used to open the calendar pane.
-.md-datepicker-button { ... }
+.mat-datepicker-button { ... }
 
 // Floating pane that contains the calendar at the bottom of the input.
-.md-datepicker-calendar-pane { ... }
+.mat-datepicker-calendar-pane { ... }
 
 // Portion of the floating panel that sits, invisibly, on top of the input.
-.md-datepicker-input-mask { }
-``` 
+.mat-datepicker-input-mask { }
+```