docs(material/datepicker): show API docs for mat-calendar and add an … (#22794)

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

* docs(material/datepicker): address feedback

(cherry picked from commit 763b7eb)

Author: mmalerba

src/components-examples/material/datepicker/BUILD.bazel

@@ -20,6 +20,7 @@ ng_module(
         "//src/cdk/testing/testbed",
         "//src/material-moment-adapter",
         "//src/material/button",
+        "//src/material/card",
         "//src/material/core",
         "//src/material/datepicker",
         "//src/material/datepicker/testing",

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

@@ -0,0 +1,3 @@
+.demo-inline-calendar-card {
+  width: 300px;
+}

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

@@ -0,0 +1,4 @@
+<mat-card class="demo-inline-calendar-card">
+  <mat-calendar (selectedChange)="selected = $event"></mat-calendar>
+</mat-card>
+<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,25 @@
 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 {MatCardModule} from '@angular/material/card';
 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 +33,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 +47,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 +59,7 @@ export {
   DatepickerFilterExample,
   DatepickerFormatsExample,
   DatepickerHarnessExample,
+  DatepickerInlineCalendarExample,
   DatepickerLocaleExample,
   DatepickerMinMaxExample,
   DatepickerMomentExample,
@@ -82,6 +87,7 @@ const EXAMPLES = [
   DatepickerFilterExample,
   DatepickerFormatsExample,
   DatepickerHarnessExample,
+  DatepickerInlineCalendarExample,
   DatepickerLocaleExample,
   DatepickerMinMaxExample,
   DatepickerMomentExample,
@@ -102,6 +108,7 @@ const EXAMPLES = [
   imports: [
     CommonModule,
     MatButtonModule,
+    MatCardModule,
     MatDatepickerModule,
     MatInputModule,
     MatIconModule,

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: