feat(month picker): address most of the review comments #3126

IgniteUI · Feb 13, 2019 · 1a5e56d · 1a5e56d
1 parent 893e59d
commit 1a5e56d
Show file tree

Hide file tree

Showing 9 changed files with 207 additions and 23 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 All notable changes for each version of this project will be documented in this file.
 ## 7.2.0
+- `igxCalendar`
+    - `igxCalendar` has been refactored to provide the ability to instantiate each view as a separate component.
+    - **Feature** advanced keyboard navigation support has been added. Read up more information in the [ReadMe](https://github.com/IgniteUI/igniteui-angular/tree/master/projects/igniteui-angular/src/lib/calendar/README.md)
+
+- **New component** `IgxMonthPicker`:
+    - Provides the ability to pick a specific month. Read up more information in the [ReadMe](https://github.com/IgniteUI/igniteui-angular/tree/master/projects/igniteui-angular/src/lib/month-picker/README.md)
+
 - **New component** `IgxHierarchicalGrid`:
     - Provides the ability to represent and manipulate hierarchical data in which each level has a different schema. Each level is represented by a component derived from **igx-grid** and supports most of its functionality. Read up more information about the IgxHierarchicalGrid in the official [documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/hierarchicalgrid.html) or the [ReadMe](https://github.com/IgniteUI/igniteui-angular/tree/master/projects/igniteui-angular/src/lib/grids/hierarchical-grid/README.md)
 

diff --git a/projects/igniteui-angular/src/lib/calendar/calendar.component.html b/projects/igniteui-angular/src/lib/calendar/calendar.component.html
@@ -52,13 +52,13 @@ <h2 class="igx-calendar__header-date">
 <igx-months-view *ngIf="isYearView" [@animateView]="activeView" #months
                                     [date]="viewDate"
                                     [locale]="locale"
-                                    [monthFormat]="_formatOptions.month"
+                                    [monthFormat]="formatOptions.month"
                                     (onSelection)="changeMonth($event)" >
 </igx-months-view>
 
 <igx-years-view *ngIf="isDecadeView" [@animateView]="activeView" #decade
                                      [date]="viewDate"
                                      [locale]="locale"
-                                     [yearFormat]="_formatOptions.year"
+                                     [yearFormat]="formatOptions.year"
                                      (onSelection)="changeYear($event)">
 </igx-years-view>
diff --git a/projects/igniteui-angular/src/lib/calendar/calendar.component.ts b/projects/igniteui-angular/src/lib/calendar/calendar.component.ts
@@ -367,12 +367,12 @@ export class IgxCalendarComponent extends IgxDaysViewComponent {
     /**
      * @hidden
      */
-    public previousMonth() {
+    public previousMonth(isKeydownTrigger: boolean = false) {
         this.viewDate = this.calendarModel.timedelta(this.viewDate, 'month', -1);
         this._monthAction = 'prev';
 
         if (this.daysView) {
-            this.daysView.isKeydownTrigger = false;
+            this.daysView.isKeydownTrigger = isKeydownTrigger;
         }
     }
 
@@ -384,22 +384,19 @@ export class IgxCalendarComponent extends IgxDaysViewComponent {
             event.preventDefault();
             event.stopPropagation();
 
-            this.previousMonth();
-            if (this.daysView) {
-                this.daysView.isKeydownTrigger = true;
-            }
+            this.previousMonth(true);
         }
     }
 
     /**
      * @hidden
      */
-    public nextMonth() {
+    public nextMonth(isKeydownTrigger: boolean = false) {
         this.viewDate = this.calendarModel.timedelta(this.viewDate, 'month', 1);
         this._monthAction = 'next';
 
         if (this.daysView) {
-            this.daysView.isKeydownTrigger = false;
+            this.daysView.isKeydownTrigger = isKeydownTrigger;
         }
     }
 
@@ -411,10 +408,7 @@ export class IgxCalendarComponent extends IgxDaysViewComponent {
             event.preventDefault();
             event.stopPropagation();
 
-            this.nextMonth();
-            if (this.daysView) {
-                this.daysView.isKeydownTrigger = true;
-            }
+            this.nextMonth(true);
         }
     }
 

diff --git a/projects/igniteui-angular/src/lib/calendar/calendar.ts b/projects/igniteui-angular/src/lib/calendar/calendar.ts
@@ -121,6 +121,13 @@ export interface IFormattedParts {
     combined: string;
 }
 
+export interface IFormattingOptions {
+    day?: string;
+    month?: string;
+    weekday?: string;
+    year?: string;
+}
+
 export enum WEEKDAYS {
     SUNDAY = 0,
     MONDAY = 1,

diff --git a/projects/igniteui-angular/src/lib/calendar/days-view/days-view.component.ts b/projects/igniteui-angular/src/lib/calendar/days-view/days-view.component.ts
@@ -9,7 +9,7 @@ import {
     HostBinding,
     DoCheck
 } from '@angular/core';
-import { ICalendarDate, Calendar, WEEKDAYS, isDateInRanges } from '../../calendar';
+import { ICalendarDate, Calendar, WEEKDAYS, isDateInRanges, IFormattingOptions } from '../../calendar';
 import { trigger, transition, useAnimation } from '@angular/animations';
 import { slideInLeft, slideInRight } from '../../animations/main';
 import { NG_VALUE_ACCESSOR, ControlValueAccessor } from '@angular/forms';
@@ -18,12 +18,18 @@ import { DateRangeDescriptor, DateRangeType } from '../../core/dates';
 
 let NEXT_ID = 0;
 
+/**
+ * Sets the calender view - days, months or years.
+ */
 export enum CalendarView {
     DEFAULT,
     YEAR,
     DECADE
 }
 
+/**
+ * Sets the selction type - single, multi or range.
+ */
 export enum CalendarSelection {
     SINGLE = 'single',
     MULTI = 'multi',
@@ -84,6 +90,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get weekStart(): WEEKDAYS | number {
         return this.calendarModel.firstWeekDay;
     }
+
     /**
      * Sets the start day of the week.
      * Can be assigned to a numeric value or to `WEEKDAYS` enum value.
@@ -108,6 +115,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get locale(): string {
         return this._locale;
     }
+
     /**
      * Sets the `locale` of the calendar.
      * Expects a valid BCP 47 language tag.
@@ -137,6 +145,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get selection(): string {
         return this._selection;
     }
+
     /**
      * Sets the selection type of the calendar.
      * ```html
@@ -173,6 +182,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get viewDate(): Date {
         return this._viewDate;
     }
+
     /**
      * Sets the date that will be presented in the default view when the calendar renders.
      * ```html
@@ -199,6 +209,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get value(): Date | Date[] {
         return this.selectedDates;
     }
+
     /**
      * Sets the selected date(s) of the calendar.
      *
@@ -221,17 +232,18 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
      * ```
      */
     @Input()
-    public get formatOptions(): object {
+    public get formatOptions(): IFormattingOptions {
         return this._formatOptions;
     }
+
     /**
      * Sets the date format options of the calendar.
      * ```html
      * <igx-calendar> [formatOptions] = "{ day: '2-digit', month: 'short', weekday: 'long', year: 'numeric' }"</igx-calendar>
      * ```
      * @memberof IgxCalendarComponent
      */
-    public set formatOptions(formatOptions: object) {
+    public set formatOptions(formatOptions: IFormattingOptions) {
         this._formatOptions = Object.assign(this._formatOptions, formatOptions);
         this.initFormatters();
     }
@@ -246,6 +258,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get disabledDates(): DateRangeDescriptor[] {
         return this._disabledDates;
     }
+
     /**
      * Sets the disabled dates' descriptors.
      * ```typescript
@@ -272,6 +285,7 @@ export class IgxDaysViewComponent implements ControlValueAccessor, DoCheck {
     public get specialDates(): DateRangeDescriptor[] {
         return this._specialDates;
     }
+
     /**
      * Sets the special dates' descriptors.
      * ```typescript

diff --git a/projects/igniteui-angular/src/lib/calendar/years-view/years-view.component.ts b/projects/igniteui-angular/src/lib/calendar/years-view/years-view.component.ts
@@ -251,7 +251,7 @@ export class IgxYearsViewComponent implements ControlValueAccessor {
      * @hidden
      */
     @HostListener('keydown.arrowdown', ['$event'])
-    public onKeydownArrowDown(event) {
+    public onKeydownArrowDown(event: KeyboardEvent) {
         event.preventDefault();
         event.stopPropagation();
 
@@ -262,7 +262,7 @@ export class IgxYearsViewComponent implements ControlValueAccessor {
      * @hidden
      */
     @HostListener('keydown.arrowup', ['$event'])
-    public onKeydownArrowUp(event) {
+    public onKeydownArrowUp(event: KeyboardEvent) {
         event.preventDefault();
         event.stopPropagation();
 

diff --git a/projects/igniteui-angular/src/lib/month-picker/README.md b/projects/igniteui-angular/src/lib/month-picker/README.md
@@ -0,0 +1,124 @@
+# igxMonthPicker Component
+
+The **igxMonthPicker** provides a way for the user to select date(s).
+
+
+## Dependencies
+In order to be able to use **igxMonthPicker** you should keep in mind that it is dependent on **BrowserAnimationsModule**,
+which must be imported **only once** in your application's AppModule, for example:
+```typescript
+import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
+@NgModule({
+	imports: [
+        BrowserAnimationsModule,
+        ...
+	]
+})
+export class AppModule {
+}
+```
+Also the **igxMonthPicker** uses the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) WebAPI for localization and formatting of dates. Consider using the [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them.
+
+
+## Usage
+
+Importing the month picker in your application
+```typescript
+import { IgxMonthPickerComponent } from "igniteui-angular";
+```
+
+Instantiate a month picker component and pass a date object.
+```html
+<igx-month-picker [value]="dateValue"></igx-month-picker>
+```
+
+The **igxMonthPicker** implements the `ControlValueAccessor` interface, providing two-way data-binding
+and the expected behavior when used both in Template-driven or Reactive Forms.
+```html
+<igx-month-picker [(ngModel)]="dateValue"></igx-month-picker>
+```
+
+Customize the format and set the locale
+```typescript
+    public formatOptions = {
+        month: 'long',
+        year: 'numeric'
+    };
+
+    public localeDe = 'de';
+```
+
+```html
+<igx-month-picker [formatOptions]="formatOptions" [locale]="localeDe"></igx-month-picker>
+```
+
+### Keyboard navigation
+When the **igxMonthPicker** component is focused:
+- `PageUp` will move to the previous year.
+- `PageDown` will move to the next year.
+- `Home` will focus the first month of the current year.
+- `End` will focus the last month of the current year.
+- `Tab` will navigate through the subheader buttons;
+
+When `prev` or `next` year buttons (in the subheader) are focused:
+- `Space` or `Enter` will scroll into view the next or previous year.
+
+When `years` button (in the subheader) is focused:
+- `Space` or `Enter` will open the years view.
+
+When a month inside the months view is focused:
+- Arrow keys will navigate through the months.
+- `Home` will focus the first month inside the months view.
+- `End` will focus the last month inside the months view.
+- `Enter` will select the currently focused month and close the view.
+
+
+## API Summary
+
+### Inputs
+
+- `id: string`
+
+Unique identifier of the component. If not provided it will be automatically generated.
+
+- `locale: string`
+
+Controls the locale used for formatting and displaying the dates in the month picker.
+The expected string should be a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646).
+The default value is `en`.
+
+- `viewDate: Date`
+
+Controls the year/month that will be presented in the default view when the month picker renders. By default it is the current year/month.
+
+- `value: Date`
+
+Gets and sets the selected date in the month picker component.
+
+- `formatOptions: Object`
+
+Controls the date-time components to use in formatted output, and their desired representations.
+Consult [this](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
+for additional information on the available options.
+
+The defaul values are listed below.
+```typescript
+{ day: 'numeric', month: 'short', weekday: 'short', year: 'numeric' }
+```
+
+- `formatViews: Object`
+
+Controls whether the date parts in the different month picker views should be formatted according to the provided
+`locale` and `formatOptions`.
+
+The default values are listed below.
+```typescript
+{ day: false, month: true, year: false }
+```
+
+### Outputs
+
+- `onSelection(): Date | Date[]`
+
+Event fired when a value is selected through UI interaction.
+Returns the selected value (depending on the type of selection).
diff --git a/projects/igniteui-angular/src/lib/month-picker/month-picker.component.html b/projects/igniteui-angular/src/lib/month-picker/month-picker.component.html
@@ -17,13 +17,13 @@
                      (@animateChange.done)="animationDone()"
                      [date]="viewDate"
                      [locale]="locale"
-                     [monthFormat]="_formatOptions.month"
+                     [monthFormat]="formatOptions.month"
                      (onSelection)="selectMonth($event)">
     </igx-months-view>
 </div>
 <igx-years-view *ngIf="isDecadeView" [@animateView]="activeView" #decade
                 [date]="viewDate"
                 [locale]="locale"
-                [yearFormat]="_formatOptions.year"
+                [yearFormat]="formatOptions.year"
                 (onSelection)="selectYear($event)">
 </igx-years-view>