docs: update guides and public APIs for NgModules (#961)

* docs: update guides and public APIs for NgModules

* fix bad import

* fix typo

* clarify @types and remove redundant setup

GETTING_STARTED.md

@@ -21,12 +21,14 @@ some initial config for the SystemJS module loader.
 ### Install Angular Material 2 components 
 
 Now that your project has been created, you can install any Angular Material 2 components you'd like 
-to use through npm. You can see our [list of published packages here](https://www.npmjs.com/~angular2-material).  
+to use through npm. You can see our [list of published packages here](https://www.npmjs.com/~angular2-material).
+
+Note that only packages published under the `@latest` npm tag are officially released.
 
 ```bash
 npm install --save @angular2-material/core @angular2-material/button @angular2-material/card
 ```
-Note: the core module is required as a peer dependency of other components.
+(the core module is required as a peer dependency of other components)
 
 ### Add components to vendor bundle
 
@@ -98,96 +100,43 @@ Now you should be able to import the components normally wherever you'd like to
 
 **src/app/my-project.component.ts**
 ```ts
-import { MD_CARD_DIRECTIVES } from '@angular2-material/card';
-import { MD_BUTTON_DIRECTIVES } from '@angular2-material/button';
+import { MdCardModule } from '@angular2-material/card';
+import { MdButtonModule } from '@angular2-material/button';
 ```
 
-And don't forget to add the directives to your directives array:
+Import the components in your application module:
 
-**src/app/my-project.component.ts**
+**my-app-module.ts**
 ```ts
-directives: [MD_CARD_DIRECTIVES, MD_BUTTON_DIRECTIVES]
+@NgModule({
+  imports: [MdButtonModule, MdCardModule],
+  ...
+})
 ```
 
 ### Sample Angular Material 2 projects
 
-- [Puppy Love (ng-conf 2016)](https://github.com/kara/puppy-love) - see live demo [here](https://youtu.be/rRiV_b3WsoY?t=4m20s) 
-- [Puppy Love Mobile (Google IO 2016)](https://github.com/kara/puppy-love-io)
 - [Material 2 Sample App](https://github.com/jelbourn/material2-app)
 
-### Additional steps for using Material components with forms
-
-If you're using Angular Material 2 version alpha.6 or later, you'll need to upgrade to Angular 2's 
-new forms module.  Here's how:
-
-- Install the `@angular/forms` package. If you're on Angular RC.4, install version 0.2.0.
-
-```bash
-npm install @angular/forms
-```
-
-- Change your bootstrap file to disable the old form directives and provide the new form 
-directives.    
-
-**main.ts**
-```ts
-import {disableDeprecatedForms, provideForms} from '@angular/forms'; 
+(the following are slightly out of date now)
+- [Puppy Love (ng-conf 2016)](https://github.com/kara/puppy-love) - see live demo [here](https://youtu.be/rRiV_b3WsoY?t=4m20s) 
+- [Puppy Love Mobile (Google IO 2016)](https://github.com/kara/puppy-love-io)
 
-bootstrap(MyAppComponent, [
-  disableDeprecatedForms(),
-  provideForms()
-]);
-```
 
-- Import any and all forms symbols - `NgForm`, `Validators`, etc - from `@angular/forms`. 
-Importing them from `@angular/common` will result in a `No value accessor found` error.
+### Additional setup for `md-slide-toggle` and `md-slider`:
+The slide-toggle and slider components have a dependency on [HammerJS](http://hammerjs.github.io/).
+1) Add HammerJS to your application via [npm](https://www.npmjs.com/package/hammerjs), a CDN 
+   (such as the [Google CDN](https://developers.google.com/speed/libraries/#hammerjs)), 
+   or served directly from your app.
+2) Include the typings for HammerJS in your typescript build ([more info on @types](https://blogs.msdn.microsoft.com/typescript/2016/06/15/the-future-of-declaration-files))
 
-- Update your form code to use the new APIs. See more information about the changes in the proposal 
-doc [here](https://docs.google.com/document/u/1/d/1RIezQqE4aEhBRmArIAS1mRIZtWFf6JxN_7B4meyWK0Y/pub) 
-and the official documentation [here](https://angular.io/docs/ts/latest/guide/forms.html).
 
-### Additional steps for `md-icon` setup:
+### Additional setup for `md-icon`:
 
-- If you want to use Material Design icons, load the Material Design font in your `index.html`.  `md-icon` supports any font icons or svg icons,
- so this is only one potential option.
+- If you want to use Material Design icons, load the Material Design font in your `index.html`.  
+`md-icon` supports any font icons or svg icons, so this is only one potential option.
 
 **src/index.html**
 ```html
 <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
 ```
-       
-- Include http providers in your `main.ts`: 
-
-**src/main.ts**
-```ts
-import { HTTP_PROVIDERS } from '@angular/http';
-...
-bootstrap(MyAppComponent, [
-    HTTP_PROVIDERS
-]);       
-```
-
-- Provide the icon registry at or above the component where you're using the icon:
-
-**src/app/my-project.component.ts**
- ```ts
-    import {MdIcon, MdIconRegistry} from '@angular2-material/icon';
-    ...
-    directives: [MD_CARD_DIRECTIVES, MD_BUTTON_DIRECTIVES, MdIcon],
-    providers: [MdIconRegistry]
- ```
-
-- Add the icon package to the list of Material components in your `system-config.ts`:
-
-**src/system-config.ts**
-```ts
-// put the names of any of your Material components here
-const materialPkgs:string[] = [
-  ...
-  'icon'
-];
-```
-
-
-
-

src/components/button-toggle/button-toggle.ts

@@ -383,6 +383,7 @@ export class MdButtonToggle implements OnInit {
   }
 }
 
+/** @deprecated */
 export const MD_BUTTON_TOGGLE_DIRECTIVES = [
   MdButtonToggleGroup,
   MdButtonToggleGroupMultiple,

src/components/button/button.ts

@@ -11,7 +11,7 @@ import {
 } from '@angular/core';
 import {CommonModule} from '@angular/common';
 import {BooleanFieldValue} from '@angular2-material/core/annotations/field-value';
-import {MdRippleModule} from '../../core/ripple/ripple';
+import {MdRippleModule} from '@angular2-material/core/ripple/ripple';
 
 // TODO(jelbourn): Make the `isMouseDown` stuff done with one global listener.
 // TODO(kara): Convert attribute selectors to classes when attr maps become available
@@ -157,6 +157,7 @@ export class MdAnchor extends MdButton {
 }
 
 
+/** @deprecated */
 export const MD_BUTTON_DIRECTIVES: Type[] = [MdButton, MdAnchor];
 
 

src/components/card/card.ts

@@ -74,6 +74,7 @@ TODO(kara): update link to demo site when it exists
 })
 export class MdCardTitleGroup {}
 
+/** @deprecated */
 export const MD_CARD_DIRECTIVES: any[] = [MdCard, MdCardHeader, MdCardTitleGroup];
 
 

src/components/checkbox/checkbox.ts

@@ -304,6 +304,7 @@ export class MdCheckbox implements ControlValueAccessor {
   }
 }
 
+/** @deprecated */
 export const MD_CHECKBOX_DIRECTIVES = [MdCheckbox];
 
 

src/components/grid-list/grid-list.ts

@@ -152,6 +152,7 @@ export class MdGridList implements OnInit, AfterContentChecked {
 }
 
 
+/** @deprecated */
 export const MD_GRID_LIST_DIRECTIVES: any[] = [MdGridList, MdGridTile, MdGridTileText];
 
 

src/components/icon/icon.ts

@@ -225,6 +225,7 @@ export class MdIcon implements OnChanges, OnInit, AfterViewChecked {
   }
 }
 
+/** @deprecated */
 export const MD_ICON_DIRECTIVES = [MdIcon];
 
 

src/components/input/input.ts

@@ -307,6 +307,7 @@ export class MdInput implements ControlValueAccessor, AfterContentInit, OnChange
   }
 }
 
+/** @deprecated */
 export const MD_INPUT_DIRECTIVES = [MdPlaceholder, MdInput, MdHint];
 
 

src/components/list/list.ts

@@ -65,6 +65,7 @@ export class MdListItem implements AfterContentInit {
   }
 }
 
+/** @deprecated */
 export const MD_LIST_DIRECTIVES = [MdList, MdListItem, MdListAvatar];
 
 

src/components/menu/README.md

@@ -14,30 +14,17 @@
 
 ### Setup
 
-`md-menu` relies on the existence of an app-wide `OverlayContainer`. This is the container in which 
-it will display. You'll need to import this from `@angular2-material/core` and add it to your 
-providers list on bootstrap.
+Import the MdMenu module.
 
-*main.ts*
+*my-app-module.ts*
 ```ts
-import { OverlayContainer } from '@angular2-material/core';
+import {MdMenuModule} from '@angular2-material/menu';
 
-bootstrap(AppComponent, [
-  OverlayContainer
-]);
-```
-
-You'll also want to import the menu directives and add them to your component's directives array:
-
-*my-comp.component.ts*
-```ts
-import {MD_MENU_DIRECTIVES} from '@angular2-material/menu';
-
-@Component({
+@NgModule({
+  imports: [MdMenuModule],
   ...
-  directives: [MD_MENU_DIRECTIVES]
 })
-class MyComp {}
+export class MyAppModule {}
 ```
 
 ### Simple menu

src/components/menu/menu.ts

@@ -9,6 +9,7 @@ export {MdMenu} from './menu-directive';
 export {MdMenuItem, MdMenuAnchor} from './menu-item';
 export {MdMenuTrigger} from './menu-trigger';
 
+/** @deprecated */
 export const MD_MENU_DIRECTIVES = [MdMenu, MdMenuItem, MdMenuTrigger, MdMenuAnchor];
 
 

src/components/progress-bar/progress-bar.ts

@@ -86,6 +86,7 @@ function clamp(v: number, min = 0, max = 100) {
   return Math.max(min, Math.min(max, v));
 }
 
+/** @deprecated */
 export const MD_PROGRESS_BAR_DIRECTIVES = [MdProgressBar];
 
 @NgModule({

src/components/progress-circle/progress-circle.ts

@@ -313,6 +313,7 @@ function getSvgArc(currentValue: number, rotation: number) {
   return `M${start}A${pathRadius},${pathRadius} 0 ${largeArcFlag},${arcSweep} ${end}`;
 }
 
+/** @deprecated */
 export const MD_PROGRESS_CIRCLE_DIRECTIVES = [MdProgressCircle, MdSpinner];
 
 

src/components/radio/README.md

@@ -5,18 +5,17 @@ Radio buttons allow the user to select one option from a set. Use radio buttons
 
 ### Setup
 Importing the symbols:
-```typescript
-import { MdUniqueSelectionDispatcher } from '@angular2-material/core';
-import { MD_RADIO_DIRECTIVES } from '@angular2-material/radio';
+```ts
+import { MdRadioModule } from '@angular2-material/radio';
 ```
 
 Adding providers and directives:
-```typescript
-@Component({
+```ts
+@NgModule({
+  imports: [MdRadioModule],
   ...
-  directives: [MD_RADIO_DIRECTIVES],
-  providers: [MdUniqueSelectionDispatcher]
 })
+export class MyAppModule { }
 ```
 
 ### Examples

src/components/radio/radio.ts

@@ -418,6 +418,7 @@ export class MdRadioButton implements OnInit {
   }
 }
 
+/** @deprecated */
 export const MD_RADIO_DIRECTIVES = [MdRadioGroup, MdRadioButton];
 
 

src/components/sidenav/sidenav.ts

@@ -383,6 +383,7 @@ export class MdSidenavLayout implements AfterContentInit {
 }
 
 
+/** @deprecated */
 export const MD_SIDENAV_DIRECTIVES = [MdSidenavLayout, MdSidenav];
 
 

src/components/slide-toggle/slide-toggle.ts

@@ -298,6 +298,7 @@ class SlideToggleRenderer {
 
 }
 
+/** @deprecated */
 export const MD_SLIDE_TOGGLE_DIRECTIVES = [MdSlideToggle];
 
 

src/components/slider/slider.ts

@@ -382,6 +382,7 @@ export class SliderRenderer {
   }
 }
 
+/** @deprecated */
 export const MD_SLIDER_DIRECTIVES = [MdSlider];
 
 

src/components/tabs/tabs.ts

@@ -196,6 +196,7 @@ export class MdTabGroup {
   }
 }
 
+/** @deprecated */
 export const MD_TABS_DIRECTIVES = [MdTabGroup, MdTabLabel, MdTabContent, MdTab];
 export const TABS_INTERNAL_DIRECTIVES = [MdInkBar, MdTabLabelWrapper];
 

src/components/toolbar/toolbar.ts

@@ -45,6 +45,7 @@ export class MdToolbar {
 
 }
 
+/** @deprecated */
 export const MD_TOOLBAR_DIRECTIVES = [MdToolbar];
 
 

src/components/tooltip/tooltip.ts

@@ -191,6 +191,7 @@ export class TooltipComponent {
   message: string;
 }
 
+/** @deprecated */
 export const MD_TOOLTIP_DIRECTIVES = [MdTooltip];
 
 

src/core/annotations/field-value.ts

@@ -10,6 +10,7 @@
  *   <component myField>
  * or:
  *   <component myField="">
+ * @deprecated
  */
 function booleanFieldValueFactory() {
   return function booleanFieldValueMetadata(target: any, key: string): void {

src/core/ripple/ripple.ts

@@ -166,6 +166,7 @@ export class MdRipple implements OnInit, OnDestroy, OnChanges {
   // TODO: Reactivate the background div if the user drags out and back in.
 }
 
+/** @deprecated */
 export const MD_RIPPLE_DIRECTIVES = [MdRipple];
 
 

src/demo-app/demo-app-module.ts

@@ -87,7 +87,9 @@ import {TabsDemo} from './tabs/tab-group-demo';
   ],
 })
 export class DemoAppModule {
-  constructor(appRef: ApplicationRef) {
-    appRef.bootstrap(DemoApp);
+  constructor(private _appRef: ApplicationRef) { }
+
+  ngDoBootstrap() {
+    this._appRef.bootstrap(DemoApp);
   }
 }