docs: add temporary docs for cdk (#5429)

Author: jelbourn

guides/getting-started.md

@@ -3,10 +3,10 @@ For help getting started with a new Angular app, check out the
 
 For existing apps, follow these steps to begin using Angular Material.
 
-## Step 1: Install Angular Material
+## Step 1: Install Angular Material and Angular CDK
 
 ```bash
-npm install --save @angular/material
+npm install --save @angular/material @angular/cdk
 ```
 
 ## Step 2: Animations
@@ -79,13 +79,14 @@ Whichever approach you use, be sure to import the Angular Material modules _afte
 
 Including a theme is **required** to apply all of the core and theme styles to your application.
 
-To get started with a prebuilt theme, include the following in your app's index.html:
-
-```html
-<link href="../node_modules/@angular/material/prebuilt-themes/indigo-pink.css" rel="stylesheet">
+To get started with a prebuilt theme, include one of Angular Material's prebuilt themes globally
+in your application. If you're using the Angular CLI, you can add this to your `styles.css`:
+```css
+@import "~@angular/material/prebuilt-themes/indigo-pink.css";
 ```
 
-Note that your app's project structure may have a different relative location for your node_modules.
+If you are not using the Angular CLI, you can include a prebuilt theme via a `<link>` element in
+your `index.html`.
 
 For more information on theming and instructions on how to create a custom theme, see the
 [theming guide](./theming.md).
@@ -142,6 +143,6 @@ System.config({
 ```
 
 
-## Sample Angular Material projects
-- [Material Sample App](https://github.com/jelbourn/material2-app)
-- [Angular Connect 2016 Demo](https://github.com/kara/leashed-in)
+## Example Angular Material projects
+- [material.angular.io](https://material.angular.io) -
+We build our own documentation with Angular Material!

src/cdk/a11y/README.md

@@ -0,0 +1,14 @@
+### FocusTrap
+The `cdkTrapFocus` directive traps <kbd>Tab</kbd> key focus within an element. This is intended to
+be used to create accessible experience for components like
+[modal dialogs](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), where focus must be
+constrained.
+
+This directive is declared in `A11yModule`.
+
+#### Example
+```html
+<div class="my-inner-dialog-content" cdkTrapFocus>
+  <!-- Tab and Shift + Tab will not leave this element. -->
+</div>
+```

src/cdk/a11y/focus-trap.md

@@ -0,0 +1,21 @@
+### InteractivityChecker
+`InteractivityChecker` is used to check the interactivity of an element, capturing disabled,
+visible, tabbable, and focusable states for accessibility purposes.
+
+#### Methods
+
+##### `isDisabled(element: HTMLElement): boolean` 
+Whether the given element is disabled.
+
+##### `isVisible(element: HTMLElement): boolean` 
+Whether the given element is visible. 
+
+This will capture states like `display: none` and `visibility: hidden`,
+but not things like being clipped by an `overflow: hidden` parent or being outside the viewport.
+
+##### `isFocusable(element: HTMLElement): boolean` 
+Gets whether an element can be focused by the user.
+
+##### `isTabbable(element: HTMLElement): boolean` 
+Gets whether an element can be reached via Tab key. 
+Assumes that the element has already been checked with isFocusable.

src/cdk/a11y/interactivity-checker.md

@@ -0,0 +1,40 @@
+### ListKeyManager
+`ListKeyManager` manages the focus in a list of items based on keyboard interaction. Intended to be
+used with components that correspond to a `role="menu"` or `role="listbox"` pattern.
+
+#### Properties
+
+##### `activeItemIndex`
+Index of the currently active item
+
+##### `activeItem`
+The active item
+
+#### `tabOut`
+Observable that emits any time the <kbd>Tab</kbd> key is pressed, so components can react when
+focus is shifted off of the list.
+
+#### Methods
+
+##### `withWrap(): this`
+Turns on wrapping mode, which ensures that the active item will wrap to
+the other end of list when there are no more items in the given direction.
+
+##### `setActiveItem(index: number): void` 
+Sets the active item to the item at the index specified.
+
+##### `onKeydown(event: KeyboardEvent): void` 
+Sets the active item depending on the key event passed in.
+
+##### `setFirstItemActive(): void` 
+Sets the active item to the first enabled item in the list.
+
+##### `setLastItemActive(): void` 
+Sets the active item to the last enabled item in the list.
+
+##### `setNextItemActive(): void` 
+Sets the active item to the next enabled item in the list.
+
+##### `setPreviousItemActive(): void` 
+Sets the active item to a previous enabled item in the list.
+

src/cdk/a11y/list-key-manager.md

@@ -26,7 +26,7 @@ export interface CanDisable {
 export class ListKeyManager<T extends CanDisable> {
   private _activeItemIndex: number = -1;
   private _activeItem: T;
-  private _tabOut = new Subject<null>();
+  private _tabOut = new Subject<void>();
   private _wrap: boolean = false;
 
   constructor(private _items: QueryList<T>) { }
@@ -66,7 +66,7 @@ export class ListKeyManager<T extends CanDisable> {
         break;
       case TAB:
         // Note that we shouldn't prevent the default action on tab.
-        this._tabOut.next(null);
+        this._tabOut.next();
         return;
       default:
         return;
@@ -75,12 +75,12 @@ export class ListKeyManager<T extends CanDisable> {
     event.preventDefault();
   }
 
-  /** Returns the index of the currently active item. */
+  /** Index of the currently active item. */
   get activeItemIndex(): number | null {
     return this._activeItemIndex;
   }
 
-  /** Returns the currently active item. */
+  /** The active item. */
   get activeItem(): T | null {
     return this._activeItem;
   }
@@ -118,7 +118,7 @@ export class ListKeyManager<T extends CanDisable> {
    * Observable that emits any time the TAB key is pressed, so components can react
    * when focus is shifted off of the list.
    */
-  get tabOut(): Observable<null> {
+  get tabOut(): Observable<void> {
     return this._tabOut.asObservable();
   }
 

src/cdk/a11y/list-key-manager.ts

@@ -0,0 +1,26 @@
+### LiveAnnouncer
+`LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region.
+See [the W3C's WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)
+for more information on aria-live regions. 
+
+#### Methods
+
+##### `announce(message: string, politeness?: 'off' | 'polite' | 'assertive'): void`
+Announce the given message via aria-live region. The politeness argument determines the 
+`aria-live` attribute on the announcer element, defaulting to 'polite'.
+
+#### Examples
+The LiveAnnouncer is injected into a component:
+```ts
+@Component({
+  selector: 'my-component'
+  providers: [LiveAnnouncer]
+})
+export class MyComponent {
+
+ constructor(liveAnnouncer: LiveAnnouncer) {
+   liveAnnouncer.announce("Hey Google");
+ }
+
+}
+```

src/cdk/a11y/live-announcer.md

@@ -0,0 +1,21 @@
+### BidiModule
+ 
+When including the CDK's `BidiModule`, components can inject `Directionality` to get the current
+text direction (RTL or LTR);
+
+#### Example
+```ts
+@Component({ ... }) 
+export class MyWidget {
+  private isRtl: boolean;
+  
+  constructor(dir: Directionality) {
+    this.isRtl = dir.value === 'rtl';
+    
+    dir.change.subscribe(() => {
+      this.flipDirection();
+    });
+  }
+}  
+```
+

src/cdk/bidi/bidi.md

@@ -1,15 +1,11 @@
-# Portals
-
-### Overview
-
+### Portals
 A `Portal `is a piece of UI that can be dynamically rendered to an open slot on the page.
 
-The "piece of UI" can be either a `Component` or a `TemplateRef`.
+The "piece of UI" can be either a `Component` or a `TemplateRef` and the "open slot" is 
+a `PortalHost`.
 
-The "open slot" is a `PortalHost`.
-
-Portals and PortalHosts are low-level building blocks that other concepts, such as overlays, can
-be built upon.
+Portals and PortalHosts are low-level building blocks that other concepts, such as overlays, are
+built upon.
 
 ##### `Portal<T>`
 | Method | Description |
@@ -27,14 +23,10 @@ be built upon.
 | `hasAttached: boolean` | Whether a portal is attached to the host. |
 
 
-
-
-### Using portals
-
-
+#### Portals in practice
 
 ##### `TemplatePortalDirective`
-Used to get a portal from a `<ng-template>`. `TemplatePortalDirectives` *is* a `Portal`.
+Used to get a portal from an `<ng-template>`. `TemplatePortalDirectives` *is* a `Portal`.
 
 Usage:
 ```html
@@ -45,7 +37,7 @@ Usage:
 <!-- OR -->
 
 <!-- This result here is identical to the syntax above -->
-<p *cdk-portal>
+<p *cdkPortal>
   The content of this template is captured by the portal.
 </p>
 ```
@@ -54,7 +46,8 @@ A component can use `@ViewChild` or `@ViewChildren` to get a reference to a
 `TemplatePortalDirective`.
 
 ##### `ComponentPortal`
-Used to create a portal from a component type.
+Used to create a portal from a component type. When a component is dynamically created using
+portals, it must be included in the `entryComponents` of its `NgModule`.
 
 Usage:
 ```ts
@@ -68,5 +61,5 @@ Used to add a portal host to a template. `PortalHostDirective` *is* a `PortalHos
 Usage:
 ```html
 <!-- Attaches the `userSettingsPortal` from the previous example. -->
-<ng-template [cdk-portalHost]="userSettingsPortal"></ng-template>
+<ng-template [cdkPortalHost]="userSettingsPortal"></ng-template>
 ```

src/cdk/portal/README.md src/cdk/portal/portal.mdsrc/cdk/portal/README.md renamed to src/cdk/portal/portal.md

@@ -11,7 +11,7 @@ const typescriptPackage = require('dgeni-packages/typescript');
 
 // Project configuration.
 const projectRootDir = path.resolve(__dirname, '../..');
-const sourceDir = path.resolve(projectRootDir, 'src/lib');
+const sourceDir = path.resolve(projectRootDir, 'src');
 const outputDir = path.resolve(projectRootDir, 'dist/docs/api');
 const templateDir = path.resolve(__dirname, './templates');
 
@@ -82,33 +82,42 @@ let apiDocsPackage = new DgeniPackage('material2-api-docs', dgeniPackageDeps)
   // Entry points for docs generation. All publically exported symbols found through these
   // files will have docs generated.
   readTypeScriptModules.sourceFiles = [
-    'autocomplete/index.ts',
-    'button/index.ts',
-    'button-toggle/index.ts',
-    'card/index.ts',
-    'checkbox/index.ts',
-    'chips/index.ts',
-    'core/index.ts',
-    'datepicker/index.ts',
-    'dialog/index.ts',
-    'expansion/index.ts',
-    'grid-list/index.ts',
-    'icon/index.ts',
-    'input/index.ts',
-    'list/index.ts',
-    'menu/index.ts',
-    'paginator/index.ts',
-    'progress-bar/index.ts',
-    'progress-spinner/index.ts',
-    'radio/index.ts',
-    'select/index.ts',
-    'sidenav/index.ts',
-    'slide-toggle/index.ts',
-    'slider/index.ts',
-    'snack-bar/index.ts',
-    'tabs/index.ts',
-    'toolbar/index.ts',
-    'tooltip/index.ts',
+    // @angular/cdk
+    'cdk/a11y/index.ts',
+    'cdk/bidi/index.ts',
+    'cdk/coercion/index.ts',
+    'cdk/platform/index.ts',
+    'cdk/portal/index.ts',
+    'cdk/table/index.ts',
+
+    // @angular/material
+    'lib/autocomplete/index.ts',
+    'lib/button/index.ts',
+    'lib/button-toggle/index.ts',
+    'lib/card/index.ts',
+    'lib/checkbox/index.ts',
+    'lib/chips/index.ts',
+    'lib/core/index.ts',
+    'lib/datepicker/index.ts',
+    'lib/dialog/index.ts',
+    'lib/expansion/index.ts',
+    'lib/grid-list/index.ts',
+    'lib/icon/index.ts',
+    'lib/input/index.ts',
+    'lib/list/index.ts',
+    'lib/menu/index.ts',
+    'lib/paginator/index.ts',
+    'lib/progress-bar/index.ts',
+    'lib/progress-spinner/index.ts',
+    'lib/radio/index.ts',
+    'lib/select/index.ts',
+    'lib/sidenav/index.ts',
+    'lib/slide-toggle/index.ts',
+    'lib/slider/index.ts',
+    'lib/snack-bar/index.ts',
+    'lib/tabs/index.ts',
+    'lib/toolbar/index.ts',
+    'lib/tooltip/index.ts',
   ];
 })
 
@@ -145,3 +154,7 @@ let apiDocsPackage = new DgeniPackage('material2-api-docs', dgeniPackageDeps)
 
 
 module.exports = apiDocsPackage;
+
+
+  const docs = new Dgeni([apiDocsPackage]);
+  docs.generate();