docs(material/datepicker): show API docs for mat-calendar and add an example of an inline calendar

Author: mmalerba

src/components-examples/material/datepicker/datepicker-inline-calendar/datepicker-inline-calendar-example.css

@@ -0,0 +1,4 @@
+.demo-inline-calendar {
+  border: 1px solid black;
+  width: 300px;
+}

src/components-examples/material/datepicker/datepicker-inline-calendar/datepicker-inline-calendar-example.html

@@ -0,0 +1,3 @@
+<mat-calendar class="demo-inline-calendar" (selectedChange)="selected=$event">
+</mat-calendar>
+<p>Selected date: {{selected}}</p>

src/components-examples/material/datepicker/datepicker-inline-calendar/datepicker-inline-calendar-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/** @title Datepicker inline calendar example */
+@Component({
+  selector: 'datepicker-inline-calendar-example',
+  templateUrl: 'datepicker-inline-calendar-example.html',
+  styleUrls: ['datepicker-inline-calendar-example.css'],
+})
+export class DatepickerInlineCalendarExample {
+  selected: Date | null;
+}

src/components-examples/material/datepicker/index.ts

@@ -1,11 +1,24 @@
 import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
-import {ReactiveFormsModule, FormsModule} from '@angular/forms';
+import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
 import {MatNativeDateModule} from '@angular/material/core';
 import {MatDatepickerModule} from '@angular/material/datepicker';
 import {MatIconModule} from '@angular/material/icon';
 import {MatInputModule} from '@angular/material/input';
+import {
+  DateRangePickerComparisonExample
+} from './date-range-picker-comparison/date-range-picker-comparison-example';
+import {
+  DateRangePickerFormsExample
+} from './date-range-picker-forms/date-range-picker-forms-example';
+import {
+  DateRangePickerOverviewExample
+} from './date-range-picker-overview/date-range-picker-overview-example';
+import {
+  DateRangePickerSelectionStrategyExample
+} from './date-range-picker-selection-strategy/date-range-picker-selection-strategy-example';
+import {DatepickerActionsExample} from './datepicker-actions/datepicker-actions-example';
 
 import {DatepickerApiExample} from './datepicker-api/datepicker-api-example';
 import {DatepickerColorExample} from './datepicker-color/datepicker-color-example';
@@ -19,6 +32,10 @@ import {DatepickerDisabledExample} from './datepicker-disabled/datepicker-disabl
 import {DatepickerEventsExample} from './datepicker-events/datepicker-events-example';
 import {DatepickerFilterExample} from './datepicker-filter/datepicker-filter-example';
 import {DatepickerFormatsExample} from './datepicker-formats/datepicker-formats-example';
+import {DatepickerHarnessExample} from './datepicker-harness/datepicker-harness-example';
+import {
+  DatepickerInlineCalendarExample
+} from './datepicker-inline-calendar/datepicker-inline-calendar-example';
 import {DatepickerLocaleExample} from './datepicker-locale/datepicker-locale-example';
 import {DatepickerMinMaxExample} from './datepicker-min-max/datepicker-min-max-example';
 import {DatepickerMomentExample} from './datepicker-moment/datepicker-moment-example';
@@ -29,20 +46,6 @@ import {DatepickerValueExample} from './datepicker-value/datepicker-value-exampl
 import {
   DatepickerViewsSelectionExample
 } from './datepicker-views-selection/datepicker-views-selection-example';
-import {
-  DateRangePickerOverviewExample
-} from './date-range-picker-overview/date-range-picker-overview-example';
-import {
-  DateRangePickerFormsExample
-} from './date-range-picker-forms/date-range-picker-forms-example';
-import {
-  DateRangePickerComparisonExample
-} from './date-range-picker-comparison/date-range-picker-comparison-example';
-import {
-  DateRangePickerSelectionStrategyExample
-} from './date-range-picker-selection-strategy/date-range-picker-selection-strategy-example';
-import {DatepickerHarnessExample} from './datepicker-harness/datepicker-harness-example';
-import {DatepickerActionsExample} from './datepicker-actions/datepicker-actions-example';
 
 export {
   DatepickerApiExample,
@@ -55,6 +58,7 @@ export {
   DatepickerFilterExample,
   DatepickerFormatsExample,
   DatepickerHarnessExample,
+  DatepickerInlineCalendarExample,
   DatepickerLocaleExample,
   DatepickerMinMaxExample,
   DatepickerMomentExample,

src/material/datepicker/calendar.ts

@@ -175,10 +175,7 @@ export class MatCalendarHeader<D> {
   }
 }
 
-/**
- * A calendar that is used as part of the datepicker.
- * @docs-private
- */
+/** A calendar that is used as part of the datepicker. */
 @Component({
   selector: 'mat-calendar',
   templateUrl: 'calendar.html',
@@ -381,6 +378,7 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
     this.stateChanges.next();
   }
 
+  /** Focuses the active date. */
   focusActiveCell() {
     this._getCurrentViewComponent()._focusActiveCell(false);
   }

src/material/datepicker/datepicker.md

@@ -258,6 +258,15 @@ The calendar popup can be programmatically controlled using the `open` and `clos
 
 <!-- example(datepicker-api) -->
 
+### Using `mat-calendar` inline
+
+If you want to allow the user to select a date from a calendar that is inlined on the page rather
+than contained in a popup, you can use `<mat-calendar>` directly. The calendar's height is
+determined automatically based on the width and the number of dates that need to be shown for a
+month. If you want to make the calendar larger or smaller, adjust the width rather than the height.
+
+<!-- example(datepicker-inline-calendar) -->
+
 ### Internationalization
 
 Internationalization of the datepicker is configured via four aspects: