# igxCalendar Component

The **igxCalendar** provides a way for the user to select date(s).
A walkthrough of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/calendar.html)

## Dependencies
In order to be able to use **igxCalendar** 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 **igxCalendar** 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
Be sure to consult the API below for additional information.

### Importing the calendar in your application

```typescript
import { IgxCalendarComponent } from "igniteui-angular/main";
```
or
```typescript
import { IgxCalendarComponent } from "igniteui-angular/calendar";
```

Instantiate a calendar component in single selection mode displaying the current month.
```html
<igx-calendar></igx-calendar>
```


A range selection calendar with first day of week set to Monday and an event
handler when selection is done.
```html
<igx-calendar [weekStart]="1" selection="range" (selected)="eventHandler($event)"></igx-calendar>
```

A multiple selection calendar with different locale and templating for the subheader.
```html
<igx-calendar #calendar locale="ja-JP" selection="multi">
        <ng-template igxCalendarSubheader let-format>
                <span (click)="calendar.activeView = 'decade'">{{ format.year.combined }}</span>
                <span (click)="calendar.activeView = 'year'">{{ format.month.combined | titlecase }}</span>
        </ng-template>
</igx-calendar>
```

A calendar displaying more than one month in the view and hiding the days that are outside of the current month
```html
<igx-calendar monthsViewNumber="2" [hideOutsideDays]="'true'">
</igx-calendar>
```

The **igxCalendar** implements the `ControlValueAccessor` interface, providing two-way data-binding
and the expected behavior when used both in Template-driven or Reactive Forms.


### Keyboard navigation
When the **igxCalendar** component is focused:
- `PageUp` will move to the previous month.
- `PageDown` will move to the next month.
- `Shift + PageUp` will move to the previous year.
- `Shift + PageDown` will move to the next year.
- `Home` will focus the first day of the current month (or first month if more months are displayed) hat is into view.
- `End` will focus the last day of the current month ((or last month if more months are displayed)) that is into view.
- `Tab` will navigate through the subheader buttons;

When `prev` or `next` month buttons (in the subheader) are focused:
- `Space` or `Enter` will scroll into view the next or previous month.

When `months` button (in the subheader) is focused:
- `Space` or `Enter` will open the months view.

When `year` button (in the subheader) is focused:
- `Space` or `Enter` will open the decade view.

When a day inside the current month is focused:
- Arrow keys will navigate through the days.
- Arrow keys will allow navigation to previous/next month as well.
- `Enter` will select the currently focused day.
- When more than one month view is displayed, navigating with the arrow keys should move to next/previous month after navigating from first/last day in current month.

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.

When an year inside the decade view is focused:
- Arrow keys will navigate through the years.
- `Enter` will select the currently focused year and close the view.

## API Summary

### Inputs

- `id: string`

Unique identifier of the component. If not provided it will be automatically generated.

- `vertical: boolean`

Controls the layout of the calendar component. When vertical is set to `true`
the calendar header will be rendered to the side of the calendar body.
Defaults to `false`.

- `weekStart: WEEKDAYS | number`

Controls the starting day of the weeek for the calendar.
Defaults to Sunday.

- `locale: string`

Controls the locale used for formatting and displaying the dates in the calendar.
The expected string should be a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646).
The default value is `en`.

- `selection: CalendarSelection | string`

Controls the type of selection in the calendar. Defaults to `CalendarSelection.SINGLE` which is equivalent to the string `single`.
Changing the selection type during 'runtime' will clear the previously selected values in the calendar.
The calendar header will not be rendered when the selection is either `multi` or `range`.

- `viewDate: Date`

Controls the year/month that will be presented in the default view when the calendar renders. By default it is the first day of the current year/month.

- `value: Date | Date[]`

Gets and sets the selected date(s) in the calendar component.
Both `multi` and `range` selection accepts single date values but they always return an array of date objects.

- `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 calendar views should be formatted according to the provided
`locale` and `formatOptions`. Date parts that are not formatted are rendered as plain numbers; months use their `Date.getMonth()` value, from `0` (January) to `11` (December).

The default values are listed below.
```typescript
{ day: false, month: true, year: false }
```

- `monthViewsNumber: number`
Controls the number of month views displayed. Default is 1.

- `hideOusideDays: boolean`
Controls the visibility of the dates that do not belong to the current month.

- `dayTemplate: TemplateRef<IgxCalendarDayTemplateContext> | null`
Sets a template for the content of the day cells. When not set, the template marked with the `igxCalendarDay` directive is used, if any. See [Day template](#day-template).


### Outputs

- `selected(): Date | Date[]`

Event fired when a value is selected through UI interaction.
Emits the selected value (depending on the type of selection).

- `viewDateChanged(): IViewDateChangeEventArgs`

Event fired after the month/year presented in the view is changed.
Emits an object containing the previous and current value of the `viewDate` property.

- `activeViewChanged(): CalendarView`

Event fired after the active view is changed.
Emits an CalendarView enum, indicating the `activeView` property value.


### Methods

- `selectedDate(value: Date | Date[]): void`

Sets a new value for the calendar component. **Does not** trigger `selected` event.

### Templating

The **igxCalendar** supports templating of its header and subheader parts.
Just decorate a ng-template inside the calendar with `igxCalendarHeader` or `igxCalendarSubheader` directive
and use the context returned to customize the way the date is displayed.

The template decorated with the `igxCalendarHeader` directive is rendered only when the calendar selection is set to `single`.
The `igxCalendarSubheader` is available in all selection modes and receives the context of the current view date in the days, months and years views.

Example:

```html
<igx-calendar #calendar>
        <ng-template igxCalendarHeader let-parts>
                {{ parts.weekday.combined }} {{ parts.month.combined }} {{ parts.day.value }}
        </ng-template>
        <ng-template igxCalendarSubheader let-parts>
                @switch (calendar.activeView) {
                        @case ('month') {
                                <!-- Days view: show the view date as YYYY-MM and open the months view on click -->
                                <span class="date__el" (click)="calendar.activeView = 'year'">
                                        {{ parts.date | date: 'yyyy-MM' }}
                                </span>
                        }
                        @case ('year') {
                                <!-- Months view: show the year and open the years view on click -->
                                <span class="date__el" (click)="calendar.activeView = 'decade'">
                                        {{ parts.year.combined }}
                                </span>
                        }
                        @case ('decade') {
                                <!-- Years view: the context holds the view date, so the title can be built around it -->
                                <span class="date__el">Years around {{ parts.year.value }}</span>
                        }
                }
        </ng-template>
</igx-calendar>
```

The subheader template replaces the default content of the subheader in every view, so use the calendar's
`activeView` to render the content that fits the current view and to switch between views.
#### Template context

| Name      | Type     | Description                                                                  |
| :-------- | :------: | :--------------------------------------------------------------------------- |
| date      | Date     | The date object in the context of the template. See * below for details.     |
| index     | number   | The index of the month view the subheader belongs to when `monthsViewNumber` is greater than `1`. |
| full      | string   | The full date representation returned after applying the `formatOptions`.    |
| era       | Object   | The era date component (if applicable) formatted to the supplied locale.     |
| year      | Object   | The year date component (if applicable) formatted to the supplied locale.    |
| month     | Object   | The month date component (if applicable) formatted to the supplied locale.   |
| day       | Object   | The day date component (if applicable) formatted to the supplied locale.     |
| weekday   | Object   | The weekday date component (if applicable) formatted to the supplied locale. |

\* In the `igxCalendarHeader` context this is either the current date or the current selection of the calendar.
In the `igxCalendarSubheader` context this is the same as the `viewDate` (offset by `index` months in a multi-view calendar).

**NOTE:** All of the date components (year, month, etc.) are objects with the structure
```typescript
{
        value: string;
        literal: string;
        combined: string;
}
```
where `value` is the locale string representation of the date component, `literal` is the locale string separator (if any),
and `combined` is as the name suggests the combined output of the two.

#### Day template

Decorate a `ng-template` inside the calendar with the `igxCalendarDay` directive to customize the content of the day cells,
for example to show event indicators, availability or prices. The template can also be set through the `dayTemplate` input.
Import `IgxCalendarDayTemplateDirective` (or `IGX_CALENDAR_DIRECTIVES`) together with the calendar, otherwise the
`igxCalendarDay` attribute is ignored and the default day content is rendered.

```typescript
import { IgxCalendarComponent, IgxCalendarDayTemplateDirective } from 'igniteui-angular/calendar';

@Component({
    imports: [IgxCalendarComponent, IgxCalendarDayTemplateDirective],
    ...
})
```

```html
<igx-calendar>
        <ng-template igxCalendarDay let-date let-selected="selected" let-disabled="disabled">
                <span class="day">
                        {{ date.getDate() }}
                        @if (hasEvents(date)) {
                                <span class="day__dot"></span>
                        }
                </span>
        </ng-template>
</igx-calendar>
```

```scss
.day__dot {
        // `currentColor` follows the day cell foreground, so the dot stays visible on the selected background.
        background: currentColor;
}
```

The template replaces only the default day number. The day cell keeps the selection, the keyboard navigation,
the ARIA attributes and the state styling (selected, range, current, special, disabled, etc.), so selecting a
templated day works as before and the theme still draws its selected state. The template is not rendered for hidden days
(see `hideOutsideDays`) and is used in every month view when `monthsViewNumber` is greater than `1`.
The `igx-date-picker` and `igx-date-range-picker` pass a template marked with `igxCalendarDay` to their calendar.
The directive is included in `IGX_DATE_PICKER_DIRECTIVES` and `IGX_DATE_RANGE_PICKER_DIRECTIVES`.

**NOTE:** The day cell is announced through its own `aria-label`, and the text rendered by the template is announced as
the cell description, so render readable text (e.g. "3 events") rather than symbols only. The template should not contain
focusable or interactive elements, since a click anywhere in the cell selects the date.
Use `currentColor` or the `selected` context property to keep the content readable on the selected background.

| Name               | Type    | Description                                                                         |
| :----------------- | :-----: | :---------------------------------------------------------------------------------- |
| $implicit, date    | Date    | The date of the day cell.                                                           |
| formattedDate      | string  | The default text of the day cell, formatted with `formatOptions` and `formatViews`. |
| selected           | boolean | Whether the day is rendered as selected.                                            |
| disabled           | boolean | Whether the day is disabled through `disabledDates`.                                |
| special            | boolean | Whether the day is marked as special through `specialDates`.                        |
| today              | boolean | Whether the day is the current date.                                                |
| weekend            | boolean | Whether the day is a weekend day.                                                   |
| currentMonth       | boolean | Whether the day belongs to the displayed month.                                     |
| active             | boolean | Whether the day is the active (keyboard focused) day.                               |
| firstInRange       | boolean | Whether the day is the first day of the selected or previewed range.                |
| lastInRange        | boolean | Whether the day is the last day of the selected or previewed range.                 |
| withinRange        | boolean | Whether the day is within the selected range. Always `false` unless `selection` is `range`. |
| withinPreviewRange | boolean | Whether the day is within the previewed range while a range is being selected.      |
