@api-client/ui 0.5.6 → 0.5.8

package/src/md/date-picker/ui-date-picker-modal-input.ts

@@ -18,16 +18,63 @@ export interface ModalInputDatePickerChangeEvent {
 
 /**
  * A modal date input picker for manual date entry using keyboard.
- * Ideal for compact layouts and precise date entry.
+ * Ideal for compact layouts and precise date entry. Supports both single
+ * date selection and date range selection modes.
+ *
+ * ## Features
+ * - Manual date entry with keyboard input
+ * - Single date and date range modes
+ * - Input validation with error messages
+ * - Min/max date constraints
+ * - Multiple date format support (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD)
+ * - Accessible design with proper ARIA labels and semantic HTML
+ * - Real-time validation feedback
+ *
+ * ## Events
+ *
+ * ### `date-input-change`
+ * Fired when a valid date is entered in the input fields.
+ *
+ * **Detail for range mode:**
+ * ```typescript
+ * {
+ *   range: DateRange,
+ *   formattedRange: {
+ *     start: string | null,
+ *     end: string | null
+ *   }
+ * }
+ * ```
+ *
+ * **Detail for single date mode:**
+ * ```typescript
+ * {
+ *   date: Date,
+ *   formattedDate: string
+ * }
+ * ```
+ *
+ * ### `modal-input-close`
+ * Fired when the modal is closed, either by confirmation or cancellation.
+ *
+ * **Detail:**
+ * ```typescript
+ * {
+ *   confirmed: boolean,
+ *   date?: Date | null,     // Available in single date mode
+ *   range?: DateRange | null // Available in range mode
+ * }
+ * ```
  *
  * ## Usage
  *
+ * ### Range mode (default)
  * ```html
  * <ui-date-picker-modal-input
  *   .open=${true}
  *   .selectedRange=${{ start: new Date(), end: null }}
  *   @date-input-change=${this.handleRangeChange}
- *   @close=${this.handleClose}
+ *   @modal-input-close=${this.handleClose}
  * ></ui-date-picker-modal-input>
  * ```
  *
@@ -36,6 +83,17 @@ export interface ModalInputDatePickerChangeEvent {
  * <ui-date-picker-modal-input
  *   .rangeMode=${false}
  *   .selectedDate=${new Date()}
+ *   @date-input-change=${this.handleDateChange}
+ *   @modal-input-close=${this.handleClose}
+ * ></ui-date-picker-modal-input>
+ * ```
+ *
+ * ### With constraints
+ * ```html
+ * <ui-date-picker-modal-input
+ *   .minDate=${new Date('2024-01-01')}
+ *   .maxDate=${new Date('2024-12-31')}
+ *   .locale=${'en-US'}
  * ></ui-date-picker-modal-input>
  * ```
  */
@@ -56,7 +114,7 @@ export class UiDatePickerModalInput extends LitElement {
   /**
    * Whether to use range mode (two date inputs) or single date mode
    */
-  @property({ type: Boolean }) accessor rangeMode = true
+  @property({ type: Boolean }) accessor rangeMode = false
 
   /**
    * Label for the start date (or single date)
@@ -98,35 +156,42 @@ export class UiDatePickerModalInput extends LitElement {
    */
   @property({ type: String }) accessor locale: string | undefined = undefined
 
-  @state() private accessor _startInput = ''
+  @state() private accessor startInput = ''
+
+  @state() private accessor endInput = ''
 
-  @state() private accessor _endInput = ''
+  @state() private accessor startError = ''
 
-  @state() private accessor _startError = ''
+  @state() private accessor endError = ''
 
-  @state() private accessor _endError = ''
+  constructor() {
+    super()
+    // Initialize boolean properties to false first, then set intended defaults
+    this.open = false
+    this.rangeMode = true // Default to range mode as documented
+  }
 
   override connectedCallback(): void {
     super.connectedCallback()
-    this._updateInputValues()
+    this.updateInputValues()
   }
 
   override willUpdate(changedProperties: Map<string | number | symbol, unknown>): void {
     if (changedProperties.has('selectedDate') || changedProperties.has('selectedRange')) {
-      this._updateInputValues()
+      this.updateInputValues()
     }
   }
 
-  private _updateInputValues(): void {
+  private updateInputValues(): void {
     if (this.rangeMode && this.selectedRange) {
-      this._startInput = this.selectedRange.start ? formatDate(this.selectedRange.start, this.locale) : ''
-      this._endInput = this.selectedRange.end ? formatDate(this.selectedRange.end, this.locale) : ''
+      this.startInput = this.selectedRange.start ? formatDate(this.selectedRange.start, this.locale) : ''
+      this.endInput = this.selectedRange.end ? formatDate(this.selectedRange.end, this.locale) : ''
     } else if (!this.rangeMode && this.selectedDate) {
-      this._startInput = formatDate(this.selectedDate, this.locale)
+      this.startInput = formatDate(this.selectedDate, this.locale)
     }
   }
 
-  private _validateDate(dateString: string, isEndDate = false): Date | null {
+  private validateDate(dateString: string, isEndDate = false): Date | null {
     if (!dateString.trim()) return null
 
     const parsedDate = parseDate(dateString)
@@ -138,22 +203,22 @@ export class UiDatePickerModalInput extends LitElement {
 
     // For range mode, validate end date is after start date
     if (this.rangeMode && isEndDate) {
-      const startDate = parseDate(this._startInput)
+      const startDate = parseDate(this.startInput)
       if (startDate && parsedDate < startDate) return null
     }
 
     return parsedDate
   }
 
-  private _handleStartInput(event: Event): void {
+  private handleStartInput(event: Event): void {
     const target = event.target as HTMLInputElement
-    this._startInput = target.value
-    this._startError = ''
+    this.startInput = target.value
+    this.startError = ''
 
-    if (this._startInput.trim()) {
-      const date = this._validateDate(this._startInput)
+    if (this.startInput.trim()) {
+      const date = this.validateDate(this.startInput)
       if (!date) {
-        this._startError = 'Invalid date format or out of range'
+        this.startError = 'Invalid date format or out of range'
         return
       }
 
@@ -164,68 +229,68 @@ export class UiDatePickerModalInput extends LitElement {
         this.selectedDate = date
       }
 
-      this._dispatchChangeEvent()
+      this.dispatchChangeEvent()
     }
   }
 
-  private _handleEndInput(event: Event): void {
+  private handleEndInput(event: Event): void {
     const target = event.target as HTMLInputElement
-    this._endInput = target.value
-    this._endError = ''
+    this.endInput = target.value
+    this.endError = ''
 
-    if (this._endInput.trim()) {
-      const date = this._validateDate(this._endInput, true)
+    if (this.endInput.trim()) {
+      const date = this.validateDate(this.endInput, true)
       if (!date) {
-        this._endError = 'Invalid date format, out of range, or before start date'
+        this.endError = 'Invalid date format, out of range, or before start date'
         return
       }
 
       const currentRange = this.selectedRange || { start: null, end: null }
       this.selectedRange = { ...currentRange, end: date }
-      this._dispatchChangeEvent()
+      this.dispatchChangeEvent()
     }
   }
 
-  private _handleCancel(): void {
-    this._dispatchCloseEvent(false)
+  private handleCancel(): void {
+    this.dispatchCloseEvent(false)
   }
 
-  private _handleConfirm(): void {
+  private handleConfirm(): void {
     // Validate all inputs before confirming
     let hasErrors = false
 
     if (this.rangeMode) {
-      if (!this._startInput.trim()) {
-        this._startError = 'Start date is required'
+      if (!this.startInput.trim()) {
+        this.startError = 'Start date is required'
         hasErrors = true
-      } else if (!this._validateDate(this._startInput)) {
-        this._startError = 'Invalid start date'
+      } else if (!this.validateDate(this.startInput)) {
+        this.startError = 'Invalid start date'
         hasErrors = true
       }
 
-      if (!this._endInput.trim()) {
-        this._endError = 'End date is required'
+      if (!this.endInput.trim()) {
+        this.endError = 'End date is required'
         hasErrors = true
-      } else if (!this._validateDate(this._endInput, true)) {
-        this._endError = 'Invalid end date'
+      } else if (!this.validateDate(this.endInput, true)) {
+        this.endError = 'Invalid end date'
         hasErrors = true
       }
     } else {
-      if (!this._startInput.trim()) {
-        this._startError = 'Date is required'
+      if (!this.startInput.trim()) {
+        this.startError = 'Date is required'
         hasErrors = true
-      } else if (!this._validateDate(this._startInput)) {
-        this._startError = 'Invalid date'
+      } else if (!this.validateDate(this.startInput)) {
+        this.startError = 'Invalid date'
         hasErrors = true
       }
     }
 
     if (!hasErrors) {
-      this._dispatchCloseEvent(true)
+      this.dispatchCloseEvent(true)
     }
   }
 
-  private _dispatchChangeEvent(): void {
+  private dispatchChangeEvent(): void {
     if (this.rangeMode && this.selectedRange) {
       const event: ModalInputDatePickerChangeEvent = {
         range: this.selectedRange,
@@ -256,7 +321,7 @@ export class UiDatePickerModalInput extends LitElement {
     }
   }
 
-  private _dispatchCloseEvent(confirmed: boolean): void {
+  private dispatchCloseEvent(confirmed: boolean): void {
     this.dispatchEvent(
       new CustomEvent('modal-input-close', {
         detail: {
@@ -270,80 +335,84 @@ export class UiDatePickerModalInput extends LitElement {
     )
   }
 
-  private _renderHeader(): TemplateResult {
+  private renderHeader(): TemplateResult {
     return html`
-      <div class="modal-header">
-        <h2 class="modal-title">${this.title}</h2>
-        <ui-icon-button @click=${this._handleCancel} aria-label="Close" title="Close">
+      <header class="modal-header">
+        <h2 id="modal-title" class="modal-title">${this.title}</h2>
+        <ui-icon-button @click=${this.handleCancel} aria-label="Close" title="Close">
           <ui-icon icon="close"></ui-icon>
         </ui-icon-button>
-      </div>
+      </header>
     `
   }
 
-  private _renderInputs(): TemplateResult {
+  private renderInputs(): TemplateResult {
     return html`
-      <div class="modal-content">
-        <div style="display: flex; flex-direction: column; gap: 16px; width: 100%; max-width: 400px;">
-          <ui-outlined-text-field
-            .label=${this.rangeMode ? this.startLabel : 'Date'}
-            .placeholder=${this.placeholder}
-            .value=${this._startInput}
-            .errorMessage=${this._startError}
-            .error=${!!this._startError}
-            @input=${this._handleStartInput}
-          >
-            <ui-icon slot="trailing-icon" icon="calendarToday"></ui-icon>
-          </ui-outlined-text-field>
-
-          ${this.rangeMode
-            ? html`
-                <ui-outlined-text-field
-                  .label=${this.endLabel}
-                  .placeholder=${this.placeholder}
-                  .value=${this._endInput}
-                  .errorMessage=${this._endError}
-                  .error=${!!this._endError}
-                  @input=${this._handleEndInput}
-                >
-                  <ui-icon slot="trailing-icon" icon="calendarToday"></ui-icon>
-                </ui-outlined-text-field>
-              `
-            : ''}
-
-          <div
-            style="margin-top: 16px; padding: 16px; background: var(--ui-color-surface-variant, #e7e0ec); border-radius: 12px;"
-          >
-            <p style="margin: 0; font-size: 14px; color: var(--ui-color-on-surface-variant, #49454f);">
+      <main class="modal-content">
+        <div class="input-container" role="form" aria-labelledby="modal-title">
+          <fieldset>
+            <legend class="visually-hidden">${this.rangeMode ? 'Enter date range' : 'Enter date'}</legend>
+
+            <ui-outlined-text-field
+              .label=${this.rangeMode ? this.startLabel : 'Date'}
+              .placeholder=${this.placeholder}
+              .value=${this.startInput}
+              .invalidText=${this.startError}
+              ?invalid=${!!this.startError}
+              @input=${this.handleStartInput}
+              required
+              aria-describedby="format-help"
+            >
+              <ui-icon slot="suffix" icon="calendarToday"></ui-icon>
+            </ui-outlined-text-field>
+
+            ${this.rangeMode
+              ? html`
+                  <ui-outlined-text-field
+                    .label=${this.endLabel}
+                    .placeholder=${this.placeholder}
+                    .value=${this.endInput}
+                    .invalidText=${this.endError}
+                    ?invalid=${!!this.endError}
+                    @input=${this.handleEndInput}
+                    required
+                    aria-describedby="format-help"
+                  >
+                    <ui-icon slot="suffix" icon="calendarToday"></ui-icon>
+                  </ui-outlined-text-field>
+                `
+              : ''}
+          </fieldset>
+
+          <aside id="format-help" class="format-help" role="note" aria-label="Date format information">
+            <p class="help-title">
               <strong>Supported formats:</strong><br />
               MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD
             </p>
-            <p style="margin: 8px 0 0; font-size: 14px; color: var(--ui-color-on-surface-variant, #49454f);">
-              <strong>Examples:</strong> 12/25/2024, 12-25-2024, 2024-12-25
-            </p>
-          </div>
+            <p class="help-examples"><strong>Examples:</strong> 12/25/2024, 12-25-2024, 2024-12-25</p>
+          </aside>
         </div>
-      </div>
+      </main>
     `
   }
 
-  private _renderActions(): TemplateResult {
+  private renderActions(): TemplateResult {
     const hasValidInput = this.rangeMode
-      ? this._startInput.trim() && this._endInput.trim() && !this._startError && !this._endError
-      : this._startInput.trim() && !this._startError
+      ? this.startInput.trim() && this.endInput.trim() && !this.startError && !this.endError
+      : this.startInput.trim() && !this.startError
 
     return html`
-      <div class="modal-actions">
-        <ui-button color="text" @click=${this._handleCancel}>Cancel</ui-button>
-        <ui-button color="filled" @click=${this._handleConfirm} .disabled=${!hasValidInput}> Confirm </ui-button>
-      </div>
+      <footer class="modal-actions">
+        <ui-button color="text" @click=${this.handleCancel}>Cancel</ui-button>
+        <ui-button color="filled" @click=${this.handleConfirm} .disabled=${!hasValidInput}> Confirm </ui-button>
+      </footer>
     `
   }
 
   override render(): TemplateResult {
     return html`
-      <ui-dialog .open=${this.open} @close=${this._handleCancel}>
-        ${this._renderHeader()} ${this._renderInputs()} ${this._renderActions()}
+      <ui-dialog .open=${this.open} @close=${this.handleCancel}>
+        ${this.renderHeader()} ${this.renderInputs()} ${this.renderActions()}
       </ui-dialog>
     `
   }