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

package/calendar/src/components/calendar-body/calendar-body.component.ts

@@ -0,0 +1,665 @@
+import {
+    Component,
+    EventEmitter,
+    Injector,
+    Input,
+    Output,
+    SimpleChanges,
+    inject,
+    OnChanges,
+    AfterViewChecked,
+    OnDestroy,
+    ElementRef,
+    NgZone,
+    afterNextRender
+} from '@angular/core';
+import { OptionalType } from '@updevs/sdk/types';
+import { DateService } from '@updevs/sdk/core';
+
+import { CalendarCellModel } from '../../models/calendar-cell.model';
+import { CalendarUserEventModel } from '../../models/calendar-user-event.model';
+import { activeCapturingEventOptions, passiveCapturingEventOptions, passiveEventOptions } from '../../tools/events-options';
+import { CalendarSignalsService } from '../../services/calendar-signals.service';
+
+let calendarBodyId = 1;
+
+@Component({
+    selector: 'upd-calendar-body',
+    templateUrl: './calendar-body.component.html',
+    styleUrl: './calendar-body.component.scss'
+})
+export class CalendarBodyComponent implements OnChanges, AfterViewChecked, OnDestroy {
+    /**
+     * The label for the table. (e.g. "Jan 2017").
+     */
+    @Input() label!: string;
+
+    /**
+     * The cells to display in the table.
+     */
+    @Input() rows!: CalendarCellModel[][];
+
+    /**
+     * The value in the table that corresponds to today.
+     */
+    @Input() todayValue?: number;
+
+    /**
+     * Start value of the selected date range.
+     */
+    @Input() startValue?: number;
+
+    /**
+     * End value of the selected date range.
+     */
+    @Input() endValue?: number;
+
+    /**
+     * The minimum number of free cells needed to fit the label in the first row.
+     */
+    @Input() labelMinRequiredCells!: number;
+
+    /**
+     * The number of columns in the table.
+     */
+    @Input() numCols = 7;
+
+    /**
+     * The cell number of the active cell in the table.
+     */
+    @Input() activeCell = 0;
+
+    /**
+     * Whether a range is being selected.
+     */
+    @Input() isRange = false;
+
+    /**
+     * The aspect ratio (width / height) to use for the cells in the table. This aspect ratio will be
+     * maintained even as the table resizes.
+     */
+    @Input() cellAspectRatio = 1;
+
+    /**
+     * Start of the comparison range.
+     */
+    @Input() comparisonStart?: number;
+
+    /**
+     * End of the comparison range.
+     */
+    @Input() comparisonEnd?: number;
+
+    /**
+     * Start of the preview range.
+     */
+    @Input() previewStart?: number;
+
+    /**
+     * End of the preview range.
+     */
+    @Input() previewEnd?: number;
+
+    /**
+     * ARIA Accessible name of the `<input updStartDate/>`
+     */
+    @Input() startDateAccessibleName?: string;
+
+    /**
+     * ARIA Accessible name of the `<input updEndDate/>`
+     */
+    @Input() endDateAccessibleName?: string;
+
+    /**
+     * Emits when a new value is selected.
+     */
+    @Output() readonly selectedValueChange = new EventEmitter<CalendarUserEventModel<number>>();
+
+    /**
+     * Emits when the preview has changed as a result of a user action.
+     */
+    @Output() readonly previewChange = new EventEmitter<CalendarUserEventModel<OptionalType<CalendarCellModel>>>();
+
+    /**
+     * Emits the date at the possible start of a drag event.
+     */
+    @Output() readonly dragStarted = new EventEmitter<CalendarUserEventModel<Date>>();
+
+    /**
+     * Emits the date at the conclusion of a drag, or null if mouse was not released on a date.
+     */
+    @Output() readonly dragEnded = new EventEmitter<CalendarUserEventModel<OptionalType<Date>>>();
+
+    /**
+     * The number of blank cells to put at the beginning for the first row.
+     */
+    firstRowOffset!: number;
+
+    /**
+     * Padding for the individual date cells.
+     */
+    cellPadding!: string;
+
+    /**
+     * Width of an individual cell.
+     */
+    cellWidth!: string;
+
+    hoveredDate?: string;
+
+    get startDateLabelId(): string {
+        return `${this.id}-start-date`;
+    }
+    get endDateLabelId(): string {
+        return `${this.id}-end-date`;
+    }
+    get colspanClass(): string {
+        return `col-${this.firstRowOffset}`;
+    }
+
+    private didDragSinceMouseDown = false;
+    private id = `upd-calendar-body-${calendarBodyId++}`;
+    /**
+     * Used to skip the next focus event when rendering the preview range.
+     * We need a flag like this, because some browsers fire focus events asynchronously.
+     */
+    private skipNextFocus?: boolean;
+    /**
+     * Used to focus the active cell after change detection has run.
+     */
+    private focusActiveCellAfterViewChecked = false;
+
+    private readonly injector = inject(Injector);
+    private readonly elementRef = inject(ElementRef<HTMLElement>);
+    private readonly ngZone = inject(NgZone);
+    private readonly calendarSignalsService = inject(CalendarSignalsService);
+    private readonly dateService = inject(DateService);
+
+    constructor() {
+        this.ngZone.runOutsideAngular(() => {
+            const element = this.elementRef.nativeElement;
+
+            // `touchmove` is active since we need to call `preventDefault`.
+            element.addEventListener('touchmove', this.touchmoveHandler, activeCapturingEventOptions);
+            element.addEventListener('mouseenter', this.enterHandler, passiveCapturingEventOptions);
+            element.addEventListener('focus', this.enterHandler, passiveCapturingEventOptions);
+            element.addEventListener('mouseleave', this.leaveHandler, passiveCapturingEventOptions);
+            element.addEventListener('blur', this.leaveHandler, passiveCapturingEventOptions);
+            element.addEventListener('mousedown', this.mousedownHandler, passiveEventOptions);
+            element.addEventListener('touchstart', this.mousedownHandler, passiveEventOptions);
+            window.addEventListener('mouseup', this.mouseupHandler);
+            window.addEventListener('touchend', this.touchendHandler);
+        });
+    }
+
+    ngAfterViewChecked(): void {
+        if (this.focusActiveCellAfterViewChecked) {
+            this.focusActiveCell();
+            this.focusActiveCellAfterViewChecked = false;
+        }
+    }
+
+    ngOnChanges(changes: SimpleChanges): void {
+        const columnChanges = changes['numCols'];
+        const { rows, numCols } = this;
+
+        if (changes['rows'] || columnChanges) {
+            this.firstRowOffset = rows && rows.length && rows[0].length ? numCols - rows[0].length : 0;
+        }
+
+        if (changes['cellAspectRatio'] || columnChanges || !this.cellPadding) {
+            this.cellPadding = `${(50 * this.cellAspectRatio) / numCols}%`;
+        }
+
+        if (columnChanges || !this.cellWidth) {
+            this.cellWidth = `${100 / numCols}%`;
+        }
+    }
+
+    ngOnDestroy(): void {
+        const element = this.elementRef.nativeElement;
+
+        element.removeEventListener('touchmove', this.touchmoveHandler, activeCapturingEventOptions);
+        element.removeEventListener('mouseenter', this.enterHandler, passiveCapturingEventOptions);
+        element.removeEventListener('focus', this.enterHandler, passiveCapturingEventOptions);
+        element.removeEventListener('mouseleave', this.leaveHandler, passiveCapturingEventOptions);
+        element.removeEventListener('blur', this.leaveHandler, passiveCapturingEventOptions);
+        element.removeEventListener('mousedown', this.mousedownHandler, passiveEventOptions);
+        element.removeEventListener('touchstart', this.mousedownHandler, passiveEventOptions);
+        window.removeEventListener('mouseup', this.mouseupHandler);
+        window.removeEventListener('touchend', this.touchendHandler);
+    }
+
+    getIndex(colIndex: number, rowIndex: number): string {
+        return `${colIndex}${rowIndex}`;
+    }
+
+    onDateEnter(index: string): void {
+        this.hoveredDate = index;
+    }
+
+    onDateLeave(): void {
+        this.hoveredDate = undefined;
+    }
+
+    /**
+     * Tracking function for rows based on their identity. Ideally we would use some sort of
+     * key on the row, but that would require a breaking change for the `rows` input. We don't
+     * use the built-in identity tracking, because it logs warnings.
+     */
+    trackRow = (row: CalendarCellModel[]) => row;
+
+    /**
+     * Called when a cell is clicked.
+     * @param cell
+     * @param event
+     */
+    cellClicked(cell: CalendarCellModel, event: MouseEvent): void {
+        // Ignore "clicks" that are actually canceled drags (eg the user dragged off and then went back to this cell to undo).
+        if (this.didDragSinceMouseDown) {
+            return;
+        }
+
+        if (cell.isEnabled) {
+            this.selectedValueChange.emit({ value: cell.value, event });
+        }
+    }
+
+    emitActiveDateChange(cell: CalendarCellModel): void {
+        if (cell.isEnabled) {
+            const month = cell.value;
+            const oldActiveDate = this.calendarSignalsService.activeDate();
+            const tempDate = this.getDateFromDayOfMonth(oldActiveDate, month);
+
+            if (this.dateService.compare(oldActiveDate, tempDate)) {
+                this.calendarSignalsService.activeDate = tempDate;
+            }
+        }
+    }
+
+    /**
+     * Returns whether a cell should be marked as selected.
+     * @param value
+     */
+    isSelected(value: number): boolean {
+        return this.startValue === value || this.endValue === value;
+    }
+
+    /**
+     * Returns whether a cell is active.
+     * @param rowIndex
+     * @param colIndex
+     */
+    isActiveCell(rowIndex: number, colIndex: number): boolean {
+        let cellNumber = rowIndex * this.numCols + colIndex;
+
+        // Account for the fact that the first row may not have as many cells.
+        if (rowIndex) {
+            cellNumber -= this.firstRowOffset;
+        }
+
+        return cellNumber === this.activeCell;
+    }
+
+    /**
+     * Focuses the active cell after the microtask queue is empty.
+     *
+     * Adding a 0ms setTimeout seems to fix Voiceover losing focus when pressing PageUp/PageDown
+     * (issue #24330).
+     *
+     * Determined a 0ms by gradually increasing duration from 0 and testing two use cases with screen
+     * reader enabled:
+     *
+     * 1. Pressing PageUp/PageDown repeatedly with pausing between each key press.
+     * 2. Pressing and holding the PageDown key with repeated keys enabled.
+     *
+     * Test 1 worked roughly 95-99% of the time with 0ms and got a little bit better as the duration
+     * increased. Test 2 got slightly better until the duration was long enough to interfere with
+     * repeated keys. If the repeated key speed was faster than the timeout duration, then pressing
+     * and holding pagedown caused the entire page to scroll.
+     *
+     * Since repeated key speed can verify across machines, determined that any duration could
+     * potentially interfere with repeated keys. 0ms would be best because it almost entirely
+     * eliminates the focus being lost in Voiceover (#24330) without causing unintended side effects.
+     * Adding delay also complicates writing tests.
+     */
+    focusActiveCell(movePreview = true): void {
+        afterNextRender(
+            () => {
+                setTimeout(() => {
+                    const activeCell = this.elementRef.nativeElement.querySelector('.upd-calendar-body-active');
+
+                    if (!!activeCell) {
+                        if (!movePreview) {
+                            this.skipNextFocus = true;
+                        }
+
+                        activeCell.focus();
+                    }
+                });
+            },
+            { injector: this.injector }
+        );
+    }
+
+    /**
+     * Focuses the active cell after change detection has run and the microtask queue is empty.
+     */
+    scheduleFocusActiveCellAfterViewChecked(): void {
+        this.focusActiveCellAfterViewChecked = true;
+    }
+
+    /**
+     * Gets whether a value is the start of the main range.
+     * @param value
+     */
+    isRangeStart(value: number): boolean {
+        return this.isStart(value, this.startValue, this.endValue);
+    }
+
+    /** Gets whether a value is the end of the main range. */
+    isRangeEnd(value: number): boolean {
+        return this.isEnd(value, this.startValue, this.endValue);
+    }
+
+    /** Gets whether a value is within the currently-selected range. */
+    isInRange(value: number): boolean {
+        return this.isInsideRange(value, this.startValue, this.endValue, this.isRange);
+    }
+
+    /** Gets whether a value is the start of the comparison range. */
+    isComparisonStart(value: number): boolean {
+        return this.isStart(value, this.comparisonStart, this.comparisonEnd);
+    }
+
+    /** Whether the cell is a start bridge cell between the main and comparison ranges. */
+    isComparisonBridgeStart(value: number, rowIndex: number, colIndex: number) {
+        if (!this.isComparisonStart(value) || this.isRangeStart(value) || !this.isInRange(value)) {
+            return false;
+        }
+
+        let previousCell: CalendarCellModel | undefined = this.rows[rowIndex][colIndex - 1];
+
+        if (!previousCell) {
+            const previousRow = this.rows[rowIndex - 1];
+            previousCell = previousRow && previousRow[previousRow.length - 1];
+        }
+
+        return previousCell && !this.isRangeEnd(previousCell.compareValue);
+    }
+
+    /** Whether the cell is an end bridge cell between the main and comparison ranges. */
+    isComparisonBridgeEnd(value: number, rowIndex: number, colIndex: number) {
+        if (!this.isComparisonEnd(value) || this.isRangeEnd(value) || !this.isInRange(value)) {
+            return false;
+        }
+
+        let nextCell: CalendarCellModel | undefined = this.rows[rowIndex][colIndex + 1];
+
+        if (!nextCell) {
+            const nextRow = this.rows[rowIndex + 1];
+            nextCell = nextRow && nextRow[0];
+        }
+
+        return nextCell && !this.isRangeStart(nextCell.compareValue);
+    }
+
+    /** Gets whether a value is the end of the comparison range. */
+    isComparisonEnd(value: number) {
+        return this.isEnd(value, this.comparisonStart, this.comparisonEnd);
+    }
+
+    /** Gets whether a value is within the current comparison range. */
+    isInComparisonRange(value: number) {
+        return this.isInsideRange(value, this.comparisonStart, this.comparisonEnd, this.isRange);
+    }
+
+    /**
+     * Gets whether a value is the same as the start and end of the comparison range.
+     * For context, the functions that we use to determine whether something is the start/end of
+     * a range don't allow for the start and end to be on the same day, because we'd have to use
+     * much more specific CSS selectors to style them correctly in all scenarios. This is fine for
+     * the regular range, because when it happens, the selected styles take over and still show where
+     * the range would've been, however we don't have these selected styles for a comparison range.
+     * This function is used to apply a class that serves the same purpose as the one for selected
+     * dates, but it only applies in the context of a comparison range.
+     */
+    isComparisonIdentical(value: number) {
+        // Note that we don't need to null check the start/end
+        // here, because the `value` will always be defined.
+        return this.comparisonStart === this.comparisonEnd && value === this.comparisonStart;
+    }
+
+    /** Gets whether a value is the start of the preview range. */
+    isPreviewStart(value: number) {
+        return this.isStart(value, this.previewStart, this.previewEnd);
+    }
+
+    /** Gets whether a value is the end of the preview range. */
+    isPreviewEnd(value: number) {
+        return this.isEnd(value, this.previewStart, this.previewEnd);
+    }
+
+    /** Gets whether a value is inside the preview range. */
+    isInPreview(value: number) {
+        // console.log('is in range', this.isInsideRange(value, this.previewStart, this.previewEnd, this.isRange));
+        return this.isInsideRange(value, this.previewStart, this.previewEnd, this.isRange);
+    }
+
+    /** Gets ids of aria descriptions for the start and end of a date range. */
+    getDescribedby(value: number): OptionalType<string> {
+        if (!this.isRange) {
+            return undefined;
+        }
+
+        if (this.startValue === value && this.endValue === value) {
+            return `${this.startDateLabelId} ${this.endDateLabelId}`;
+        } else if (this.startValue === value) {
+            return this.startDateLabelId;
+        } else if (this.endValue === value) {
+            return this.endDateLabelId;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Event handler for when the user enters an element
+     * inside the calendar body (e.g. by hovering in or focus).
+     */
+    private enterHandler = (event: Event) => {
+        if (this.skipNextFocus && event.type === 'focus') {
+            this.skipNextFocus = false;
+            return;
+        }
+
+        // We only need to hit the zone when we're selecting a range.
+        if (!!event.target && this.isRange) {
+            const cell = this.getCellFromElement(event.target as HTMLElement);
+
+            if (cell) {
+                this.ngZone.run(() => this.previewChange.emit({ value: cell.isEnabled ? cell : undefined, event }));
+            }
+        }
+    };
+
+    private touchmoveHandler = (event: TouchEvent) => {
+        if (!this.isRange) {
+            return;
+        }
+
+        const target = this.getActualTouchTarget(event);
+        const cell = target ? this.getCellFromElement(target as HTMLElement) : undefined;
+
+        if (target !== event.target) {
+            this.didDragSinceMouseDown = true;
+        }
+
+        // If the initial target of the touch is a date cell, prevent default so
+        // that the move is not handled as a scroll.
+        if (this.getCellElement(event.target as HTMLElement)) {
+            event.preventDefault();
+        }
+
+        this.ngZone.run(() => this.previewChange.emit({ value: cell?.isEnabled ? cell : undefined, event }));
+    };
+
+    /**
+     * Event handler for when the user's pointer leaves an element
+     * inside the calendar body (e.g. by hovering out or blurring).
+     */
+    private leaveHandler = (event: Event) => {
+        // We only need to hit the zone when we're selecting a range.
+        if (this.previewEnd !== undefined && this.isRange) {
+            if (event.type !== 'blur') {
+                this.didDragSinceMouseDown = true;
+            }
+
+            // Only reset the preview end value when leaving cells. This looks better, because
+            // we have a gap between the cells and the rows and we don't want to remove the
+            // range just for it to show up again when the user moves a few pixels to the side.
+            if (
+                event.target &&
+                this.getCellFromElement(event.target as HTMLElement) &&
+                !(
+                    (event as MouseEvent).relatedTarget &&
+                    this.getCellFromElement((event as MouseEvent).relatedTarget as HTMLElement)
+                )
+            ) {
+                this.ngZone.run(() => this.previewChange.emit({ value: undefined, event }));
+            }
+        }
+    };
+
+    /**
+     * Triggered on mousedown or touchstart on a date cell.
+     * Responsible for starting a drag sequence.
+     */
+    private mousedownHandler = (event: Event) => {
+        if (!this.isRange) {
+            return;
+        }
+
+        this.didDragSinceMouseDown = false;
+        // Begin a drag if a cell within the current range was targeted.
+        const cell = event.target && this.getCellFromElement(event.target as HTMLElement);
+
+        if (!cell || !this.isInRange(cell.compareValue)) {
+            return;
+        }
+
+        this.ngZone.run(() => {
+            this.dragStarted.emit({
+                value: cell.rawValue!,
+                event
+            });
+        });
+    };
+
+    /** Triggered on mouseup anywhere. Responsible for ending a drag sequence. */
+    private mouseupHandler = (event: Event) => {
+        if (!this.isRange) {
+            return;
+        }
+
+        const cellElement = this.getCellElement(event.target as HTMLElement);
+        if (!cellElement) {
+            // Mouseup happened outside of datepicker. Cancel drag.
+            this.ngZone.run(() => {
+                this.dragEnded.emit({ value: undefined, event });
+            });
+            return;
+        }
+
+        if (cellElement.closest('.upd-calendar-body') !== this.elementRef.nativeElement) {
+            // Mouseup happened inside a different month instance.
+            // Allow it to handle the event.
+            return;
+        }
+
+        this.ngZone.run(() => {
+            const cell = this.getCellFromElement(cellElement);
+            this.dragEnded.emit({ value: cell?.rawValue ?? undefined, event });
+        });
+    };
+
+    /** Triggered on touchend anywhere. Respsonsible for ending a drag sequence. */
+    private touchendHandler = (event: TouchEvent) => {
+        const target = this.getActualTouchTarget(event);
+
+        if (target) {
+            this.mouseupHandler({ target } as unknown as Event);
+        }
+    };
+
+    /** Finds the CalendarCell that corresponds to a DOM node. */
+    private getCellFromElement(element: HTMLElement): OptionalType<CalendarCellModel> {
+        const cell = this.getCellElement(element);
+
+        if (!!cell) {
+            const row = cell.getAttribute('data-upd-row');
+            const col = cell.getAttribute('data-upd-col');
+
+            if (row && col) {
+                return this.rows[parseInt(row, 10)][parseInt(col, 10)];
+            }
+        }
+
+        return undefined;
+    }
+
+    /** Checks whether a node is a table cell element. */
+    private isTableCell(node: OptionalType<Node>): node is HTMLTableCellElement {
+        return node?.nodeName === 'DIV';
+    }
+
+    /**
+     * Gets the date table cell element that is or contains the specified element.
+     * Or returns null if element is not part of a date cell.
+     */
+    private getCellElement(element: HTMLElement): OptionalType<HTMLElement> {
+        let cell: OptionalType<HTMLElement>;
+
+        if (this.isTableCell(element)) {
+            cell = element;
+        } else if (this.isTableCell(element.parentNode || undefined)) {
+            cell = element.parentNode as HTMLElement;
+        } else if (this.isTableCell(element.parentNode?.parentNode || undefined)) {
+            cell = element.parentNode!.parentNode as HTMLElement;
+        }
+
+        return cell?.getAttribute('data-upd-row') !== undefined ? cell : undefined;
+    }
+
+    /** Checks whether a value is the start of a range. */
+    private isStart(value: number, start: OptionalType<number>, end: OptionalType<number>): boolean {
+        return end !== undefined && start !== end && value < end && value === start;
+    }
+
+    /** Checks whether a value is the end of a range. */
+    private isEnd(value: number, start: OptionalType<number>, end: OptionalType<number>): boolean {
+        return start !== undefined && start !== end && value >= start && value === end;
+    }
+
+    /** Checks whether a value is inside of a range. */
+    private isInsideRange(value: number, start: OptionalType<number>, end: OptionalType<number>, rangeEnabled: boolean): boolean {
+        return (rangeEnabled && start !== undefined && end !== undefined && start !== end && value >= start && value <= end);
+    }
+
+    /**
+     * Extracts the element that actually corresponds to a touch event's location
+     * (rather than the element that initiated the sequence of touch events).
+     */
+    private getActualTouchTarget(event: TouchEvent): Element | null {
+        const touchLocation = event.changedTouches[0];
+        return document.elementFromPoint(touchLocation.clientX, touchLocation.clientY);
+    }
+
+    /**
+     * 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(activeDate: Date, dayOfMonth: number): Date {
+        return this.dateService.create(activeDate.getFullYear(), activeDate.getMonth(), dayOfMonth);
+    }
+}

package/calendar/src/components/calendar-header/calendar-header.component.html

@@ -0,0 +1,27 @@
+<ng-container *transloco="let t; prefix: 'UpDevs.Calendar'">
+    <div class="container">
+        <div class="row">
+            <div class="col d-flex">
+                <label [id]="periodButtonLabelId" class="visually-hidden" aria-live="polite">
+                    {{ periodText || t('YearRangeLabel', { start: minYearOfPageLabel, end: maxYearOfPageLabel }) }}
+                </label>
+
+                <upd-button [isIcon]="true" [iconModel]="{tablerIcon:'chevron-left'}" [isDisabled]="!previousEnabled()"
+                    (clicked)="previousClicked()" [attr.aria-label]="t(prevButtonLabel)">
+                </upd-button>
+
+                <upd-button (click)="currentPeriodClicked()" [attr.aria-label]="t(periodButtonLabel)"
+                    [attr.aria-describedby]="periodButtonLabelId" customClasses="mx-1 flex-grow-1">
+                    <span aria-hidden="true">
+                        {{ periodText || t('YearRange', { start: minYearOfPageLabel, end: maxYearOfPageLabel }) }}
+                    </span>
+                    <upd-icon [tablerIcon]="!isNotMonth ? 'chevron-down' : 'chevron-up'"></upd-icon>
+                </upd-button>
+
+                <upd-button [isIcon]="true" [iconModel]="{tablerIcon:'chevron-right'}" [isDisabled]="!nextEnabled()"
+                    (clicked)="nextClicked()" [attr.aria-label]="t(nextButtonLabel)">
+                </upd-button>
+            </div>
+        </div>
+    </div>
+</ng-container>

package/calendar/src/components/calendar-header/calendar-header.component.scss

@@ -0,0 +1 @@
+