@updevs/components 1.0.0-alpha.8 → 1.0.0-alpha.9

package/calendar/src/components/calendar-month-view/calendar-month-view.component.ts

@@ -0,0 +1,540 @@
+import {
+    AfterContentInit,
+    ChangeDetectorRef,
+    Component,
+    EventEmitter,
+    Input,
+    OnChanges,
+    Output,
+    SimpleChanges,
+    ViewChild,
+    effect,
+    inject
+} from '@angular/core';
+import { OptionalType } from '@updevs/sdk/types';
+import { DateService } from '@updevs/sdk/core';
+import { BaseComponent } from '@updevs/sdk/layout';
+import { TranslocoService } from '@jsverse/transloco';
+import { startWith } from 'rxjs';
+
+import { CalendarUserEventModel } from '../../models/calendar-user-event.model';
+import { CalendarBodyComponent } from '../calendar-body/calendar-body.component';
+import { DateRangeModel } from '../../models/date-range.model';
+import { CalendarCellModel } from '../../models/calendar-cell.model';
+import { CalendarCellClassFunctionType } from '../../types/calendar-cell-class-function.type';
+import { KeyboardTools } from '../../tools/keyboard-tools';
+import { CalendarRangeStrategyService } from '../../services/calendar-range-strategy.service';
+import { CalendarSignalsService } from '../../services/calendar-signals.service';
+
+const daysPerWeek = 7;
+
+let uniqueIdCounter = 0;
+
+@Component({
+    selector: 'upd-calendar-month-view',
+    templateUrl: './calendar-month-view.component.html',
+    styleUrl: './calendar-month-view.component.scss'
+})
+export class CalendarMonthViewComponent extends BaseComponent implements AfterContentInit, OnChanges {
+    /**
+     * The body of calendar table
+     */
+    @ViewChild(CalendarBodyComponent) _matCalendarBody!: CalendarBodyComponent;
+
+    /**
+     * The date to display in this month view (everything other than the month and year is ignored).
+     */
+    @Input()
+    get activeDate(): Date {
+        return this.calendarSignalsService.activeDate();
+    }
+    set activeDate(value: Date) {
+        this.updateActiveDate(value);
+    }
+
+    /** The currently selected date. */
+    @Input()
+    get selected(): DateRangeModel | OptionalType<Date> {
+        return this.calendarSignalsService.selectedDate();
+    }
+    set selected(value: DateRangeModel | OptionalType<Date>) {
+        let currValue: DateRangeModel | OptionalType<Date>;
+
+        if (value instanceof DateRangeModel) {
+            currValue = value;
+        } else {
+            currValue = this.dateService.getValidOrUndefined(this.dateService.deserialize(value));
+        }
+
+        this.calendarSignalsService.selectedDate = currValue;
+
+        this.setRanges(currValue);
+    }
+
+    /** The minimum selectable date. */
+    @Input()
+    get minDate(): OptionalType<Date> {
+        return this._minDate;
+    }
+    set minDate(value: OptionalType<Date>) {
+        this._minDate = this.dateService.getValidOrUndefined(this.dateService.deserialize(value));
+    }
+
+    /** The maximum selectable date. */
+    @Input()
+    get maxDate(): OptionalType<Date> {
+        return this._maxDate;
+    }
+    set maxDate(value: OptionalType<Date>) {
+        this._maxDate = this.dateService.getValidOrUndefined(this.dateService.deserialize(value));
+    }
+
+    /** Function used to filter which dates are selectable. */
+    @Input() dateFilter?: (date: Date) => boolean;
+
+    /** Function that can be used to add custom CSS classes to dates. */
+    @Input() dateClass?: CalendarCellClassFunctionType;
+
+    /** Start of the comparison range. */
+    @Input() comparisonStart?: Date;
+
+    /** End of the comparison range. */
+    @Input() comparisonEnd?: Date;
+
+    /** ARIA Accessible name of the `<input matStartDate/>` */
+    @Input() startDateAccessibleName?: string;
+
+    /** ARIA Accessible name of the `<input matEndDate/>` */
+    @Input() endDateAccessibleName?: string;
+
+    /**
+     * First day of week.
+     * Zero-based starting from Sunday.
+     * Default: 0 - Sunday.
+     */
+    @Input() firstDayOfWeek = 0;
+
+    /** Origin of active drag, or null when dragging is not active. */
+    @Input() activeDrag?: CalendarUserEventModel<Date>;
+
+    /** Whether the user is currently selecting a range of dates. */
+    @Input() isRange = false;
+
+    /** Emits when a new date is selected. */
+    @Output() readonly selectedChange = new EventEmitter<OptionalType<Date>>();
+
+    /** Emits when any date is selected. */
+    @Output() readonly userSelection = new EventEmitter<CalendarUserEventModel<OptionalType<Date>>>();
+
+    /** Emits when the user initiates a date range drag via mouse or touch. */
+    @Output() readonly dragStarted = new EventEmitter<CalendarUserEventModel<Date>>();
+
+    /**
+     * Emits when the user completes or cancels a date range drag.
+     * Emits null when the drag was canceled or the newly selected date range if completed.
+     */
+    @Output() readonly dragEnded = new EventEmitter<CalendarUserEventModel<OptionalType<DateRangeModel>>>();
+
+    /** Emits when any date is activated. */
+    @Output() readonly activeDateChange = new EventEmitter<Date>();
+
+    /** The label for this month (e.g. "January 2017"). */
+    monthLabel!: string;
+
+    /** Grid of calendar cells representing the dates of the month. */
+    weeks: CalendarCellModel[][] = [];
+
+    /** The number of blank cells in the first row before the 1st of the month. */
+    firstWeekOffset = 0;
+
+    /** Start value of the currently-shown date range. */
+    rangeStart?: number;
+
+    /** End value of the currently-shown date range. */
+    rangeEnd?: number;
+
+    /** Start value of the currently-shown comparison date range. */
+    comparisonRangeStart?: number;
+
+    /** End value of the currently-shown comparison date range. */
+    comparisonRangeEnd?: number;
+
+    /** Start of the preview range. */
+    previewStart?: number;
+
+    /** End of the preview range. */
+    previewEnd?: number;
+
+    /** The date of the month that today falls on. Null if today is in another month. */
+    todayDate?: number;
+
+    /** The names of the weekdays. */
+    weekdays: { long: string; narrow: string; id: number }[] = [];
+
+    /** Flag used to filter out space/enter keyup events that originated outside of the view. */
+    private _selectionKeyPressed = false;
+    private _minDate?: Date;
+    private _maxDate?: Date;
+    private oldActiveDate?: Date;
+
+    private readonly translocoService = inject(TranslocoService);
+    private readonly changeDetectorRef = inject(ChangeDetectorRef);
+    private readonly dateService = inject(DateService);
+    private readonly calendarSignalsService = inject(CalendarSignalsService);
+    private readonly calendarRangeStrategy = inject(CalendarRangeStrategyService);
+
+    constructor() {
+        super();
+        effect(() => this.updateActiveDate(this.calendarSignalsService.activeDate(), true));
+    }
+
+    ngAfterContentInit(): void {
+        const langSub = this.translocoService.langChanges$
+            .pipe(startWith(undefined))
+            .subscribe(() => this.init());
+        this.addSubscriptions(langSub);
+    }
+
+    ngOnChanges(changes: SimpleChanges): void {
+        const comparisonChange = changes['comparisonStart'] || changes['comparisonEnd'];
+
+        if (comparisonChange && !comparisonChange.firstChange) {
+            this.setRanges(this.selected);
+        }
+
+        if (changes['activeDrag'] && !this.activeDrag) {
+            this.clearPreview();
+        }
+    }
+
+    /** Handles when a new date is selected. */
+    dateSelected(event: CalendarUserEventModel<number>): void {
+        const date = event.value;
+        const selectedDate = this.getDateFromDayOfMonth(date);
+        const currSelection = this.calendarSignalsService.selectedDate();
+        let rangeStartDate: OptionalType<number>;
+        let rangeEndDate: OptionalType<number>;
+
+        if (currSelection instanceof DateRangeModel) {
+            rangeStartDate = this.getDateInCurrentMonth(currSelection.start);
+            rangeEndDate = this.getDateInCurrentMonth(currSelection.end);
+        } else {
+            rangeStartDate = rangeEndDate = this.getDateInCurrentMonth(currSelection);
+        }
+
+        if (rangeStartDate !== date || rangeEndDate !== date) {
+            this.calendarSignalsService.selectedDate = selectedDate;
+        }
+
+        this.userSelection.emit({ value: selectedDate, event: event.event });
+        this.clearPreview();
+        this.changeDetectorRef.markForCheck();
+    }
+
+    /** Handles keydown events on the calendar body when calendar is in month view. */
+    handleCalendarBodyKeydown(event: KeyboardEvent): void {
+        // TODO(mmalerba): We currently allow keyboard navigation to disabled dates, but just prevent
+        // disabled ones from being selected. This may not be ideal, we should look into whether
+        // navigation should skip over disabled dates, and if so, how to implement that efficiently.
+
+        const oldActiveDate = this.activeDate;
+        let tempActiveDate: OptionalType<Date>;
+
+        switch (event.key) {
+            case 'LEFT_ARROW':
+                tempActiveDate = this.dateService.addDays(this.activeDate, -1);
+                break;
+            case 'RIGHT_ARROW':
+                tempActiveDate = this.dateService.addDays(this.activeDate, 1);
+                break;
+            case 'UP_ARROW':
+                tempActiveDate = this.dateService.addDays(this.activeDate, -7);
+                break;
+            case 'DOWN_ARROW':
+                tempActiveDate = this.dateService.addDays(this.activeDate, 7);
+                break;
+            case 'HOME':
+                tempActiveDate = this.dateService.addDays(this.activeDate, 1 - this.activeDate.getDate());
+                break;
+            case 'END':
+                tempActiveDate = this.dateService.addDays(
+                    this.activeDate,
+                    this.dateService.getNumDaysInMonth(this.activeDate) -
+                    this.activeDate.getDate()
+                );
+                break;
+            case 'PAGE_UP':
+                tempActiveDate = event.altKey
+                    ? this.dateService.addYears(this.activeDate, -1)
+                    : this.dateService.addMonths(this.activeDate, -1);
+                break;
+            case 'PAGE_DOWN':
+                tempActiveDate = event.altKey
+                    ? this.dateService.addYears(this.activeDate, 1)
+                    : this.dateService.addMonths(this.activeDate, 1);
+                break;
+            case 'ENTER':
+            case 'SPACE':
+                this._selectionKeyPressed = true;
+
+                if (this.canSelect(this.activeDate)) {
+                    // Prevent unexpected default actions such as form submission.
+                    // Note that we only prevent the default action here while the selection happens in
+                    // `keyup` below. We can't do the selection here, because it can cause the calendar to
+                    // reopen if focus is restored immediately. We also can't call `preventDefault` on `keyup`
+                    // because it's too late (see #23305).
+                    event.preventDefault();
+                }
+                return;
+            case 'ESCAPE':
+                // Abort the current range selection if the user presses escape mid-selection.
+                if (this.previewEnd !== undefined && !KeyboardTools.hasModifierKey(event)) {
+                    this.clearPreview();
+                    // If a drag is in progress, cancel the drag without changing the
+                    // current selection.
+                    if (this.activeDrag) {
+                        this.dragEnded.emit({ value: undefined, event });
+                    } else {
+                        this.selectedChange.emit(undefined);
+                        this.userSelection.emit({ value: undefined, event });
+                    }
+                    event.preventDefault();
+                    event.stopPropagation(); // Prevents the overlay from closing.
+                }
+                return;
+            default:
+                // Don't prevent default or focus active cell on keys that we don't explicitly handle.
+                return;
+        }
+
+        if (this.dateService.compare(oldActiveDate, this.activeDate)) {
+            this.calendarSignalsService.activeDate = tempActiveDate;
+            this.focusActiveCellAfterViewChecked();
+        }
+
+        // Prevent unexpected default actions such as form submission.
+        event.preventDefault();
+    }
+
+    /** Handles keyup events on the calendar body when calendar is in month view. */
+    handleCalendarBodyKeyup(event: KeyboardEvent): void {
+        if (event.key === 'SPACE' || event.key === 'ENTER') {
+            if (this._selectionKeyPressed && this.canSelect(this.activeDate)) {
+                this.dateSelected({ value: this.activeDate.getDate(), event });
+            }
+
+            this._selectionKeyPressed = false;
+        }
+    }
+
+    /** Initializes this month view. */
+    init(): void {
+        this.setRanges(this.selected);
+        this.todayDate = this.getCellCompareValue(new Date());
+        this.monthLabel = this.dateService.getMonthNames('short')[this.activeDate.getMonth()].toLocaleUpperCase();
+        const firstOfMonth = this.dateService.create(
+            this.activeDate.getFullYear(),
+            this.activeDate.getMonth(),
+            1
+        );
+        this.firstWeekOffset = (daysPerWeek + firstOfMonth.getDay() - this.firstDayOfWeek) % daysPerWeek;
+
+        this.initWeekdays();
+        this.createWeekCells();
+        this.changeDetectorRef.markForCheck();
+    }
+
+    /** Focuses the active cell after the microtask queue is empty. */
+    focusActiveCell(movePreview?: boolean): void {
+        this._matCalendarBody.focusActiveCell(movePreview);
+    }
+
+    /** Focuses the active cell after change detection has run and the microtask queue is empty. */
+    focusActiveCellAfterViewChecked(): void {
+        this._matCalendarBody.scheduleFocusActiveCellAfterViewChecked();
+    }
+
+    /** Called when the user has activated a new cell and the preview needs to be updated. */
+    previewChanged({ value: cell }: CalendarUserEventModel<OptionalType<CalendarCellModel>>): void {
+        if (!this.selected) {
+            return;
+        }
+
+        if (this.isRange && !(this.selected instanceof DateRangeModel)) {
+            this.selected = new DateRangeModel(this.selected);
+        }
+
+        // We can assume that this will be a range, because preview
+        // events aren't fired for single date selections.
+        const value = cell ? cell.rawValue! : undefined;
+        const previewRange = this.calendarRangeStrategy.createPreview(value, this.selected as DateRangeModel);
+        this.previewStart = this.getCellCompareValue(previewRange.start);
+        this.previewEnd = this.getCellCompareValue(previewRange.end);
+
+        if (!!this.activeDrag && !!value) {
+            const dragRange = this.calendarRangeStrategy.createDrag?.(this.activeDrag.value, this.selected as DateRangeModel, value);
+
+            if (!!dragRange) {
+                this.previewStart = this.getCellCompareValue(dragRange.start);
+                this.previewEnd = this.getCellCompareValue(dragRange.end);
+            }
+        }
+
+        // Note that here we need to use `detectChanges`, rather than `markForCheck`, because
+        // the way `_focusActiveCell` is set up at the moment makes it fire at the wrong time
+        // when navigating one month back using the keyboard which will cause this handler
+        // to throw a "changed after checked" error when updating the preview state.
+        this.changeDetectorRef.detectChanges();
+    }
+
+    /**
+     * Called when the user has ended a drag. If the drag/drop was successful,
+     * computes and emits the new range selection.
+     */
+    protected _dragEnded(event: CalendarUserEventModel<OptionalType<Date>>): void {
+        if (!this.activeDrag) {
+            return;
+        }
+
+        if (event.value) {
+            // Propagate drag effect
+            const dragDropResult = this.calendarRangeStrategy?.createDrag?.(
+                this.activeDrag.value,
+                this.selected as DateRangeModel,
+                event.value
+            );
+
+            this.dragEnded.emit({ value: dragDropResult ?? undefined, event: event.event });
+        } else {
+            this.dragEnded.emit({ value: undefined, event: event.event });
+        }
+    }
+
+    private updateActiveDate(value: Date, isFromEffect = false): void {
+        this.oldActiveDate = this.oldActiveDate || value;
+        const validDate = this.dateService.getValidOrUndefined(this.dateService.deserialize(value)) || new Date();
+
+        if (!isFromEffect) {
+            this.calendarSignalsService.activeDate = this.dateService.clamp(validDate, this.minDate, this.maxDate);
+        }
+
+        if (!this.isSameMonthAndYearAsActiveDate(this.oldActiveDate, this.calendarSignalsService.activeDate())) {
+            this.init();
+        }
+
+        this.oldActiveDate = value;
+
+        this.activeDateChange.emit(this.calendarSignalsService.activeDate());
+    }
+
+    /**
+     * Takes a day of the month and returns a new date in the same month and year as the currently
+     *  active date. The returned date will have the same day of the month as the argument date.
+     */
+    private getDateFromDayOfMonth(dayOfMonth: number): Date {
+        return this.dateService.create(this.activeDate.getFullYear(), this.activeDate.getMonth(), dayOfMonth);
+    }
+
+    /** Initializes the weekdays. */
+    private initWeekdays(): void {
+        const firstDayOfWeek = this.firstDayOfWeek;
+        const narrowWeekdays = this.dateService.getDayOfWeekNames('narrow');
+        const longWeekdays = this.dateService.getDayOfWeekNames('long');
+        // Rotate the labels for days of the week based on the configured first day of the week.
+        const weekdays = longWeekdays.map((long, i) => ({ long, narrow: narrowWeekdays[i], id: uniqueIdCounter++ }));
+        this.weekdays = weekdays.slice(firstDayOfWeek).concat(weekdays.slice(0, firstDayOfWeek));
+    }
+
+    /** Creates MatCalendarCells for the dates in this month. */
+    private createWeekCells(): void {
+        const daysInMonth = this.dateService.getNumDaysInMonth(this.activeDate);
+        const dateNames = this.dateService.getDateNames();
+        this.weeks = [[]];
+
+        for (let i = 0, cell = this.firstWeekOffset; i < daysInMonth; i++, cell++) {
+            if (cell === daysPerWeek) {
+                this.weeks.push([]);
+                cell = 0;
+            }
+
+            const date = this.dateService.create(this.activeDate.getFullYear(), this.activeDate.getMonth(), i + 1);
+            const isEnabled = this.shouldEnableDate(date);
+            const ariaLabel = this.dateService.format(date, { year: 'numeric', month: 'long', day: 'numeric' });
+            const cellClasses = this.dateClass ? this.dateClass(date, 'month') : undefined;
+
+            this.weeks[this.weeks.length - 1].push(
+                new CalendarCellModel(
+                    i + 1,
+                    dateNames[i],
+                    ariaLabel,
+                    isEnabled,
+                    cellClasses,
+                    this.getCellCompareValue(date)!,
+                    date
+                )
+            );
+        }
+    }
+
+    /** Date filter for the month */
+    private shouldEnableDate(date: Date): boolean {
+        return !!date &&
+            (!this.minDate || this.dateService.compare(date, this.minDate) >= 0) &&
+            (!this.maxDate || this.dateService.compare(date, this.maxDate) <= 0) &&
+            (!this.dateFilter || this.dateFilter(date));
+    }
+
+    /**
+     * Gets the date in this month that the given Date falls on.
+     * Returns null if the given Date is in another month.
+     */
+    private getDateInCurrentMonth(date?: Date): OptionalType<number> {
+        return !!date && this.isSameMonthAndYearAsActiveDate(date, this.calendarSignalsService.activeDate())
+            ? date.getDate()
+            : undefined;
+    }
+
+    /** Checks whether the 2 dates are non-null and fall within the same month of the same year. */
+    private isSameMonthAndYearAsActiveDate(d1?: Date, d2?: Date): boolean {
+        return (!!d1 && !!d2 && d1.getMonth() === d2.getMonth() && d1.getFullYear() === d2.getFullYear());
+    }
+
+    /** Gets the value that will be used to one cell to another. */
+    private getCellCompareValue(date?: Date): OptionalType<number> {
+        if (!!date) {
+            // We use the time since the Unix epoch to compare dates in this view, rather than the
+            // cell values, because we need to support ranges that span across multiple months/years.
+            const year = date.getFullYear();
+            const month = date.getMonth();
+            const day = date.getDate();
+
+            return new Date(year, month, day).getTime();
+        }
+
+        return undefined;
+    }
+
+    /** Sets the current range based on a model value. */
+    private setRanges(selectedValue: DateRangeModel | OptionalType<Date>): void {
+        if (selectedValue instanceof DateRangeModel) {
+            this.rangeStart = this.getCellCompareValue(selectedValue.start);
+            this.rangeEnd = this.getCellCompareValue(selectedValue.end);
+            this.isRange = true;
+        } else {
+            this.rangeStart = this.rangeEnd = this.getCellCompareValue(selectedValue);
+        }
+
+        this.comparisonRangeStart = this.getCellCompareValue(this.comparisonStart);
+        this.comparisonRangeEnd = this.getCellCompareValue(this.comparisonEnd);
+    }
+
+    /** Gets whether a date can be selected in the month view. */
+    private canSelect(date: Date): boolean {
+        return !this.dateFilter || this.dateFilter(date);
+    }
+
+    /** Clears out preview state. */
+    private clearPreview(): void {
+        this.previewStart = this.previewEnd = undefined;
+    }
+}

package/calendar/src/components/calendar-multi-year-view/calendar-multi-year-view.component.html

@@ -0,0 +1 @@
+<p>calendar-multi-year-view works!</p>

package/calendar/src/components/calendar-multi-year-view/calendar-multi-year-view.component.scss

@@ -0,0 +1 @@
+

package/calendar/src/components/calendar-multi-year-view/calendar-multi-year-view.component.spec.ts

@@ -0,0 +1,21 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { CalendarMultiYearViewComponent } from './calendar-multi-year-view.component';
+
+describe('CalendarMultiYearViewComponent', () => {
+  let component: CalendarMultiYearViewComponent;
+  let fixture: ComponentFixture<CalendarMultiYearViewComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      declarations: [CalendarMultiYearViewComponent]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(CalendarMultiYearViewComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/calendar/src/components/calendar-multi-year-view/calendar-multi-year-view.component.ts

@@ -0,0 +1,19 @@
+import { Component } from '@angular/core';
+
+export const yearsPerPage = 24;
+
+@Component({
+    selector: 'upd-calendar-multi-year-view',
+    templateUrl: './calendar-multi-year-view.component.html',
+    styleUrl: './calendar-multi-year-view.component.scss'
+})
+export class CalendarMultiYearViewComponent {
+    /** Initializes this month view. */
+    init(): void {
+
+    }
+
+    /** Focuses the active cell after the microtask queue is empty. */
+    focusActiveCell(movePreview?: boolean): void {
+    }
+}

package/calendar/src/components/calendar-year-view/calendar-year-view.component.html

@@ -0,0 +1 @@
+<p>calendar-year-view works!</p>

package/calendar/src/components/calendar-year-view/calendar-year-view.component.scss

@@ -0,0 +1 @@
+

package/calendar/src/components/calendar-year-view/calendar-year-view.component.spec.ts

@@ -0,0 +1,21 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { CalendarYearViewComponent } from './calendar-year-view.component';
+
+describe('CalendarYearViewComponent', () => {
+  let component: CalendarYearViewComponent;
+  let fixture: ComponentFixture<CalendarYearViewComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      declarations: [CalendarYearViewComponent]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(CalendarYearViewComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/calendar/src/components/calendar-year-view/calendar-year-view.component.ts

@@ -0,0 +1,17 @@
+import { Component } from '@angular/core';
+
+@Component({
+    selector: 'upd-calendar-year-view',
+    templateUrl: './calendar-year-view.component.html',
+    styleUrl: './calendar-year-view.component.scss'
+})
+export class CalendarYearViewComponent {
+    /** Initializes this month view. */
+    init(): void {
+
+    }
+
+    /** Focuses the active cell after the microtask queue is empty. */
+    focusActiveCell(movePreview?: boolean): void {
+    }
+}

package/calendar/src/models/calendar-cell.model.ts

@@ -0,0 +1,22 @@
+import { CalendarCellCssClassesType } from '../types/calendar-cell-css-classes.type';
+
+let uniqueIdCounter = 0;
+
+/**
+ * An internal class that represents the data corresponding to a single calendar cell.
+ * @docs-private
+ */
+export class CalendarCellModel {
+    readonly id = uniqueIdCounter++;
+
+    constructor(
+        public value: number,
+        public displayValue: string,
+        public ariaLabel: string,
+        public isEnabled: boolean,
+        public cssClasses: CalendarCellCssClassesType = {},
+        public compareValue = value,
+        public rawValue?: Date
+    ) {
+    }
+}

package/calendar/src/models/calendar-user-event.model.ts

@@ -0,0 +1,4 @@
+export interface CalendarUserEventModel<TValue> {
+    value: TValue;
+    event: Event;
+}

package/calendar/src/models/date-range.model.ts

@@ -0,0 +1,22 @@
+/**
+ * A class representing a range of dates.
+ */
+export class DateRangeModel {
+    /**
+     * Ensures that objects with a `start` and `end` property can't be assigned to a variable that
+     * expects a `DateRange`
+     */// @ts-ignore
+    private disableStructuralEquivalency: never;
+
+    constructor(
+        /**
+         * The start date of the range.
+         */
+        readonly start?: Date,
+        /**
+         * The end date of the range.
+         */
+        readonly end?: Date
+    ) {
+    }
+}