@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/date-picker/date-input.js

@@ -4,15 +4,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { html, nothing } from 'lit';
+import { html, nothing, } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { FormAssociated } from '../../internal/form-associated.js';
+import { SET_ANCHORED_VALIDITY } from '../../internal/anchored-validity.js';
 import { defineElement } from '../../internal/prefix.js';
 import { place } from '../../internal/positioner.js';
 import { nextId } from '../../internal/a11y.js';
 import { closeIcon, calendarIcon } from '../../internal/icons.js';
-import { parseISO, formatISO } from './calendar-core.js';
+import { composedContains, deepActiveElement } from '../../internal/overlay-manager.js';
+import { dateTimeFormat, parseISO, formatISO, normalizeCalendarMonths, normalizeWeekdayFormat, } from './calendar-core.js';
 import { styles } from './date-input.styles.js';
 import { LyraDatePicker } from './date-picker.js';
 import './date-picker.js';
@@ -36,6 +38,14 @@ function localeDateOrder(locale) {
         return ['month', 'day', 'year']; // Date.parse()'s own bias, as a last-resort fallback
     }
 }
+const monthsConverter = {
+    fromAttribute: normalizeCalendarMonths,
+    toAttribute: normalizeCalendarMonths,
+};
+const weekdayFormatConverter = {
+    fromAttribute: normalizeWeekdayFormat,
+    toAttribute: normalizeWeekdayFormat,
+};
 /**
  * `<lyra-date-input>` — a date field with an attached calendar popover.
  * Mirrors the core `<wa-date-input>` API under `lyra-`. Value is ISO 8601
@@ -49,31 +59,52 @@ function localeDateOrder(locale) {
  * @event change - Fired on committed date transitions.
  * @event lyra-show / lyra-hide - Calendar popover lifecycle.
  * @event lyra-clear - The clear button was used.
- * @csspart form-control, form-control-label, input-wrapper, input, clear-button, expand-button, expand-icon, popup, date-picker, hint, error
+ * @csspart form-control - The outer form-control wrapper.
+ * @csspart form-control-label - The label wrapper.
+ * @csspart input-wrapper - The input and button wrapper.
+ * @csspart input - The text input.
+ * @csspart clear-button - The clear control.
+ * @csspart expand-button - The calendar popup toggle.
+ * @csspart expand-icon - The calendar icon.
+ * @csspart popup - The positioned calendar popup.
+ * @csspart date-picker - The nested date picker.
+ * @csspart hint - The hint message.
+ * @csspart error - The validation message.
  * @slot label - Custom label content.
  * @slot error - Custom error content.
  * @slot hint - Custom hint content.
  */
 export class LyraDateInput extends FormAssociated(LyraElement) {
+    static { this.styles = [LyraElement.styles, styles]; }
+    static { this.properties = {
+        mode: { noAccessor: true },
+        min: { noAccessor: true },
+        max: { noAccessor: true },
+        readonly: { type: Boolean, reflect: true, noAccessor: true },
+        disablePast: { type: Boolean, attribute: 'disable-past', noAccessor: true },
+        disableFuture: { type: Boolean, attribute: 'disable-future', noAccessor: true },
+    }; }
     constructor() {
-        super(...arguments);
-        this.mode = 'single';
-        this.min = '';
-        this.max = '';
-        this.readonly = false;
+        super();
         this.open = false;
         this.withClear = false;
         this.label = '';
         this.hint = '';
         this.errorText = '';
         this.placeholder = '';
+        this.accessibleLabel = null;
         this.locale = '';
         this.months = 1;
         this.firstDayOfWeek = 'auto';
         this.weekdayFormat = 'short';
-        this.disablePast = false;
-        this.disableFuture = false;
         this.withOutsideDays = false;
+        /** Accessible label for the clear button. Override for a non-English `locale`. */
+        this.clearLabel = 'Clear';
+        /** Accessible label for the calendar-toggle button. Override for a non-English `locale`. */
+        this.openLabel = 'Open calendar';
+        /** Accessible name for the calendar popover dialog. Override for a non-English `locale`. */
+        this.dialogLabel = 'Choose date';
+        this.restorePopupFocusOnClose = false;
         this.inputId = nextId('date-input');
         this.popupId = nextId('date-popup');
         // Set on the date input's first `blur`; gates the `data-invalid`
@@ -89,6 +120,13 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
         this.hasHintSlot = false;
         this.hasErrorSlot = false;
         this.hasLabelSlot = false;
+        this._mode = 'single';
+        this._min = '';
+        this._max = '';
+        this._readonly = false;
+        this._disablePast = false;
+        this._disableFuture = false;
+        this.typedBadInput = false;
         this.onDocPointer = (e) => {
             if (!e.composedPath().includes(this))
                 this.hide();
@@ -105,19 +143,19 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
                 return;
             }
             const parsed = this.mode === 'range' ? this.parseRangeText(raw) : this.parseSingleText(raw);
-            if (parsed && this.isWithinBounds(parsed)) {
+            if (parsed) {
                 this.value = parsed;
                 this.emit('input');
                 this.emit('change');
             }
             else {
-                // Unparseable (or out-of-bounds) text: don't silently keep the
-                // committed value while the field still shows garbage -- revert the
-                // displayed text back to the last valid commit and flag the
-                // constraint-validation state (mirrors how `required` is already
-                // wired via internals.setValidity(), see form-associated.ts).
+                // Unparseable text: don't silently keep the committed value while the
+                // field still shows garbage -- revert the display to the last commit
+                // and flag bad input. Parseable dates outside an active bound instead
+                // commit above and expose their precise range validity state.
                 target.value = this.displayText;
-                this.internals.setValidity({ badInput: true }, 'Enter a valid date');
+                this.setTypedBadInput(true);
+                this.updateValidity();
             }
         };
         this.onInputKey = (e) => {
@@ -133,8 +171,7 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
         this.onFormControlKey = (e) => {
             if (e.key === 'Escape' && this.open) {
                 e.preventDefault();
-                this.hide();
-                this.renderRoot.querySelector('[part="expand-button"]')?.focus();
+                this.hide(true);
             }
         };
         this.onInputBlur = () => {
@@ -167,25 +204,193 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             // The picker only fires `change` once a selection is finalized (a single
             // pick, or the second click of a range), so this is always the right
             // moment to close, in either mode.
-            this.hide();
+            this.hide(true);
         };
+        this.addEventListener('invalid', () => {
+            this.touched = true;
+        });
+    }
+    get mode() {
+        return this._mode;
+    }
+    set mode(next) {
+        const old = this._mode;
+        this._mode = next === 'range' ? 'range' : 'single';
+        this.updateValidity();
+        this.requestUpdate('mode', old);
+    }
+    get min() {
+        return this._min;
+    }
+    set min(next) {
+        const old = this._min;
+        this._min = next ?? '';
+        this.updateValidity();
+        this.requestUpdate('min', old);
+    }
+    get max() {
+        return this._max;
+    }
+    set max(next) {
+        const old = this._max;
+        this._max = next ?? '';
+        this.updateValidity();
+        this.requestUpdate('max', old);
+    }
+    get readonly() {
+        return this._readonly;
+    }
+    set readonly(next) {
+        const old = this._readonly;
+        this._readonly = Boolean(next);
+        this.toggleAttribute('readonly', this._readonly);
+        this.updateValidity();
+        this.requestUpdate('readonly', old);
+    }
+    get disablePast() {
+        return this._disablePast;
+    }
+    set disablePast(next) {
+        const old = this._disablePast;
+        this._disablePast = Boolean(next);
+        this.updateValidity();
+        this.requestUpdate('disablePast', old);
+    }
+    get disableFuture() {
+        return this._disableFuture;
+    }
+    set disableFuture(next) {
+        const old = this._disableFuture;
+        this._disableFuture = Boolean(next);
+        this.updateValidity();
+        this.requestUpdate('disableFuture', old);
+    }
+    get value() {
+        return super.value;
+    }
+    set value(next) {
+        this.setTypedBadInput(false);
+        super.value = this.normalizeCommittedValue(next ?? '');
+    }
+    setTypedBadInput(next) {
+        const old = this.typedBadInput;
+        this.typedBadInput = next;
+        if (old !== next)
+            this.requestUpdate('typedBadInput', old);
+    }
+    parseStrictISO(value) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+            return null;
+        return parseISO(value);
+    }
+    normalizeCommittedValue(value) {
+        if (value === '')
+            return '';
+        const parts = value.split('/');
+        if (parts.length !== 1 && parts.length !== 2)
+            return '';
+        const dates = parts.map((part) => this.parseStrictISO(part));
+        if (dates.some((date) => date === null))
+            return '';
+        if (parts.length === 2 && dates[0] > dates[1])
+            return `${parts[1]}/${parts[0]}`;
+        return value;
+    }
+    valueDates(value) {
+        const parts = value.split('/');
+        const expectedParts = this.mode === 'range' ? 2 : 1;
+        if (parts.length !== expectedParts)
+            return null;
+        const dates = parts.map((part) => this.parseStrictISO(part));
+        return dates.some((date) => date === null) ? null : dates;
+    }
+    updateValidity() {
+        if (this.readonly) {
+            this[SET_ANCHORED_VALIDITY]({});
+            return;
+        }
+        const flags = {};
+        let underflowMessage = '';
+        let overflowMessage = '';
+        if (this.required && this.value === '')
+            flags.valueMissing = true;
+        if (this.typedBadInput)
+            flags.badInput = true;
+        if (this.value !== '') {
+            const dates = this.valueDates(this.value);
+            if (!dates) {
+                flags.badInput = true;
+            }
+            else {
+                const min = this.parseStrictISO(this.min);
+                const max = this.parseStrictISO(this.max);
+                const today = new Date();
+                today.setHours(0, 0, 0, 0);
+                if (min !== null && dates.some((date) => date < min)) {
+                    flags.rangeUnderflow = true;
+                    underflowMessage = `Date must be on or after ${this.min}.`;
+                }
+                if (this.disablePast && dates.some((date) => date < today)) {
+                    flags.rangeUnderflow = true;
+                    underflowMessage ||= 'Date cannot be in the past.';
+                }
+                if (max !== null && dates.some((date) => date > max)) {
+                    flags.rangeOverflow = true;
+                    overflowMessage = `Date must be on or before ${this.max}.`;
+                }
+                if (this.disableFuture && dates.some((date) => date > today)) {
+                    flags.rangeOverflow = true;
+                    overflowMessage ||= 'Date cannot be in the future.';
+                }
+            }
+        }
+        let message = '';
+        if (flags.badInput)
+            message = 'Enter a valid date.';
+        else if (flags.rangeUnderflow)
+            message = underflowMessage;
+        else if (flags.rangeOverflow)
+            message = overflowMessage;
+        else if (flags.valueMissing)
+            message = 'Please fill out this field.';
+        this[SET_ANCHORED_VALIDITY](flags, message);
     }
-    static { this.styles = [LyraElement.styles, styles]; }
     get displayText() {
         const parts = this.value.split('/');
         const from = parseISO(parts[0] ?? '');
         const to = parseISO(parts[1] ?? '');
         if (!from)
             return '';
-        const fmt = (d) => d.toLocaleDateString(this.locale || undefined);
+        const formatter = dateTimeFormat(this.locale, {});
+        const fmt = (d) => formatter.format(d);
         return this.mode === 'range' && to ? `${fmt(from)} – ${fmt(to)}` : fmt(from);
     }
-    willUpdate() {
+    willUpdate(changed) {
         if (!this.hasUpdated) {
             this.hasHintSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'hint');
             this.hasErrorSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'error');
             this.hasLabelSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'label');
         }
+        if (changed.has('open')) {
+            if (this.open) {
+                if (!this.popupTrigger) {
+                    const active = deepActiveElement(this.ownerDocument);
+                    this.popupTrigger = active && typeof active.focus === 'function' ? active : undefined;
+                }
+                this.ownerDocument.addEventListener('pointerdown', this.onDocPointer);
+            }
+            else {
+                this.ownerDocument.removeEventListener('pointerdown', this.onDocPointer);
+                const active = deepActiveElement(this.ownerDocument);
+                const popup = this.renderRoot.querySelector('[part="popup"]');
+                const restoreFocus = this.restorePopupFocusOnClose || (popup !== null && composedContains(popup, active));
+                const trigger = this.popupTrigger;
+                this.popupTrigger = undefined;
+                this.restorePopupFocusOnClose = false;
+                if (restoreFocus && trigger?.isConnected)
+                    trigger.focus();
+            }
+        }
     }
     /** Open the calendar popover. */
     show() {
@@ -193,18 +398,22 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             return;
         this.open = true;
         this.emit('lyra-show');
-        document.addEventListener('pointerdown', this.onDocPointer);
     }
     /** Close the calendar popover. */
-    hide() {
+    hide(restoreFocus = false) {
         if (!this.open)
             return;
+        this.restorePopupFocusOnClose ||= restoreFocus;
         this.open = false;
         this.emit('lyra-hide');
-        document.removeEventListener('pointerdown', this.onDocPointer);
     }
     /** Clear the value. */
     clear() {
+        // Matches how `onInputBlur` already flips this on the first blur -- an
+        // explicit user-initiated clear() is itself an interaction, so a
+        // required-and-now-empty field must surface its invalid state right
+        // away instead of silently looking valid until some later blur.
+        this.touched = true;
         this.value = '';
         this.emit('input');
         this.emit('change');
@@ -214,7 +423,9 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
         super.disconnectedCallback();
         this.cleanupFn?.();
         this.cleanupFn = undefined;
-        document.removeEventListener('pointerdown', this.onDocPointer);
+        this.ownerDocument.removeEventListener('pointerdown', this.onDocPointer);
+        this.popupTrigger = undefined;
+        this.restorePopupFocusOnClose = false;
         // Reset so a reconnect (e.g. a drag-drop reparent) re-triggers
         // `updated()`'s `open`-driven branch -- without this, `open` stays
         // stuck `true` across the disconnect, `updated()` never sees it
@@ -234,7 +445,16 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
                     this.cleanupFn = place(anchor, popup);
             }
         }
-        if (changed.has('touched') || changed.has('required') || changed.has('value')) {
+        if (changed.has('touched') ||
+            changed.has('required') ||
+            changed.has('value') ||
+            changed.has('mode') ||
+            changed.has('min') ||
+            changed.has('max') ||
+            changed.has('readonly') ||
+            changed.has('disablePast') ||
+            changed.has('disableFuture') ||
+            changed.has('typedBadInput')) {
             this.toggleAttribute('data-invalid', this.touched && !this.internals.validity.valid);
         }
     }
@@ -304,31 +524,19 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             return null;
         return from <= to ? `${formatISO(from)}/${formatISO(to)}` : `${formatISO(to)}/${formatISO(from)}`;
     }
-    isWithinBounds(isoValue) {
-        const min = parseISO(this.min);
-        const max = parseISO(this.max);
-        const today = new Date();
-        today.setHours(0, 0, 0, 0);
-        return isoValue.split('/').every((part) => {
-            const d = parseISO(part);
-            if (!d)
-                return false;
-            if (min && d < min)
-                return false;
-            if (max && d > max)
-                return false;
-            if (this.disablePast && d < today)
-                return false;
-            if (this.disableFuture && d > today)
-                return false;
-            return true;
-        });
+    formStateRestoreCallback(state, _mode) {
+        this.value = typeof state === 'string' ? state : '';
+    }
+    formResetCallback() {
+        super.formResetCallback();
+        this.touched = false;
     }
     render() {
         const hasValue = this.value.length > 0;
         const hasHint = this.hasHintSlot || this.hint.length > 0;
         const hasError = this.hasErrorSlot || this.errorText.length > 0;
         const hasLabel = this.hasLabelSlot || this.label.length > 0;
+        const invalid = this.touched && !this.internals.validity.valid;
         const describedBy = [hasError ? 'date-input-error' : '', hasHint ? 'date-input-hint' : '']
             .filter(Boolean)
             .join(' ');
@@ -342,10 +550,13 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             id=${this.inputId}
             part="input"
             type="text"
-            aria-label=${hasLabel ? nothing : this.placeholder || 'Date'}
+            aria-label=${this.accessibleLabel || (hasLabel ? nothing : this.placeholder || 'Date')}
             aria-describedby=${describedBy || nothing}
+            aria-required=${this.required ? 'true' : 'false'}
+            aria-invalid=${invalid ? 'true' : 'false'}
             .value=${this.displayText}
             placeholder=${this.placeholder}
+            ?required=${this.required}
             ?disabled=${this.effectiveDisabled}
             ?readonly=${this.readonly}
             @change=${this.onInputChange}
@@ -357,7 +568,7 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
                 part="clear-button"
                 type="button"
                 ?disabled=${this.effectiveDisabled || this.readonly}
-                aria-label="Clear"
+                aria-label=${this.clearLabel}
                 @click=${() => this.clear()}
               >
                 ${closeIcon()}
@@ -366,7 +577,7 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
           <button
             part="expand-button"
             type="button"
-            aria-label="Open calendar"
+            aria-label=${this.openLabel}
             aria-haspopup="dialog"
             aria-expanded=${this.open ? 'true' : 'false'}
             aria-controls=${this.popupId}
@@ -376,14 +587,14 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             <span part="expand-icon" aria-hidden="true">${calendarIcon()}</span>
           </button>
         </div>
-        <div id=${this.popupId} part="popup" role="dialog" aria-label="Choose date">
+        <div id=${this.popupId} part="popup" role="dialog" aria-label=${this.dialogLabel}>
           <lyra-date-picker
             part="date-picker"
             .value=${this.value}
             .mode=${this.mode}
             .min=${this.min}
             .max=${this.max}
-            .months=${this.months}
+            .months=${normalizeCalendarMonths(this.months)}
             .locale=${this.locale}
             .disabled=${this.effectiveDisabled}
             .readonly=${this.readonly}
@@ -391,7 +602,7 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
             .disableFuture=${this.disableFuture}
             .withOutsideDays=${this.withOutsideDays}
             first-day-of-week=${this.firstDayOfWeek}
-            weekday-format=${this.weekdayFormat}
+            .weekdayFormat=${normalizeWeekdayFormat(this.weekdayFormat)}
             @input=${this.onPickerInput}
             @change=${this.onPickerChange}
           ></lyra-date-picker>
@@ -406,18 +617,6 @@ export class LyraDateInput extends FormAssociated(LyraElement) {
     `;
     }
 }
-__decorate([
-    property()
-], LyraDateInput.prototype, "mode", void 0);
-__decorate([
-    property()
-], LyraDateInput.prototype, "min", void 0);
-__decorate([
-    property()
-], LyraDateInput.prototype, "max", void 0);
-__decorate([
-    property({ type: Boolean, reflect: true })
-], LyraDateInput.prototype, "readonly", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraDateInput.prototype, "open", void 0);
@@ -436,27 +635,33 @@ __decorate([
 __decorate([
     property()
 ], LyraDateInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'aria-label' })
+], LyraDateInput.prototype, "accessibleLabel", void 0);
 __decorate([
     property()
 ], LyraDateInput.prototype, "locale", void 0);
 __decorate([
-    property({ type: Number })
+    property({ converter: monthsConverter })
 ], LyraDateInput.prototype, "months", void 0);
 __decorate([
     property({ attribute: 'first-day-of-week' })
 ], LyraDateInput.prototype, "firstDayOfWeek", void 0);
 __decorate([
-    property({ attribute: 'weekday-format' })
+    property({ attribute: 'weekday-format', converter: weekdayFormatConverter })
 ], LyraDateInput.prototype, "weekdayFormat", void 0);
-__decorate([
-    property({ type: Boolean, attribute: 'disable-past' })
-], LyraDateInput.prototype, "disablePast", void 0);
-__decorate([
-    property({ type: Boolean, attribute: 'disable-future' })
-], LyraDateInput.prototype, "disableFuture", void 0);
 __decorate([
     property({ type: Boolean, attribute: 'with-outside-days' })
 ], LyraDateInput.prototype, "withOutsideDays", void 0);
+__decorate([
+    property({ attribute: 'clear-label' })
+], LyraDateInput.prototype, "clearLabel", void 0);
+__decorate([
+    property({ attribute: 'open-label' })
+], LyraDateInput.prototype, "openLabel", void 0);
+__decorate([
+    property({ attribute: 'dialog-label' })
+], LyraDateInput.prototype, "dialogLabel", void 0);
 __decorate([
     state()
 ], LyraDateInput.prototype, "touched", void 0);

package/dist/components/date-picker/date-picker.d.ts

@@ -1,6 +1,6 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
-import { type WeekdayFormat } from './calendar-core.js';
+import { type CalendarMode, type WeekdayFormat } from './calendar-core.js';
 export interface DateRange {
     from: Date | null;
     to: Date | null;
@@ -14,14 +14,30 @@ export interface DateRange {
  * @customElement lyra-date-picker
  * @event change - The user committed a value.
  * @event input - The value changed during interaction (range: after the first click).
- * @csspart base, month, header, title, previous, next, weekdays, weekday, grid, week
- * @csspart day, day-today, day-outside, day-selected, day-range-start, day-range-end, day-range-inner, day-placeholder
+ * @csspart base - The date-picker wrapper.
+ * @csspart month - A visible month wrapper.
+ * @csspart header - The month header.
+ * @csspart title - The month title.
+ * @csspart previous - The previous-month button.
+ * @csspart next - The next-month button.
+ * @csspart weekdays - The weekday header row.
+ * @csspart weekday - A weekday label.
+ * @csspart grid - A month date grid.
+ * @csspart week - A calendar week row.
+ * @csspart day - A calendar day button.
+ * @csspart day-today - A day representing today.
+ * @csspart day-outside - A day outside the active month.
+ * @csspart day-selected - A selected day.
+ * @csspart day-range-start - The start of a selected range.
+ * @csspart day-range-end - The end of a selected range.
+ * @csspart day-range-inner - An interior day in a selected range.
+ * @csspart day-placeholder - A non-day grid placeholder.
  */
 export declare class LyraDatePicker extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     /** ISO value: `YYYY-MM-DD` or `YYYY-MM-DD/YYYY-MM-DD`. */
     value: string;
-    mode: 'single' | 'range';
+    mode: CalendarMode;
     min: string;
     max: string;
     disabled: boolean;
@@ -33,10 +49,18 @@ export declare class LyraDatePicker extends LyraElement {
     disablePast: boolean;
     disableFuture: boolean;
     withOutsideDays: boolean;
+    /** Accessible label for the previous-month button. Override for a non-English `locale`. */
+    previousLabel: string;
+    /** Accessible label for the next-month button. Override for a non-English `locale`. */
+    nextLabel: string;
     private viewDate;
     private focusedDate;
     private focusPending;
+    private readonly titleIds;
     private suppressViewSync;
+    private get effectiveMode();
+    private get visibleMonths();
+    private get effectiveWeekdayFormat();
     get selection(): DateRange;
     /** Read-only Date view of a single-mode value. */
     get valueAsDate(): Date | null;