@api-client/ui 0.5.6 → 0.5.8

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

@@ -11,13 +11,52 @@ import '../../md/icons/ui-icon.js'
  * A docked date picker that opens from a text field input.
  * Ideal for forms and date selection in medium to large layouts.
  *
+ * ## Features
+ * - Text field input with calendar dropdown
+ * - Keyboard navigation support (Arrow Down, Enter, Escape)
+ * - Custom date formatting
+ * - Input validation and error handling
+ * - Min/max date constraints
+ * - Disabled dates support
+ * - Accessible design with proper ARIA attributes
+ * - CSS Anchor Positioning API for dropdown placement
+ *
+ * ## Events
+ *
+ * ### `change`
+ * Fired when the selected date changes.
+ *
+ * **Detail:**
+ * ```typescript
+ * {
+ *   value: Date | null,
+ *   formattedValue: string
+ * }
+ * ```
+ *
  * ## Usage
  *
+ * ### Basic usage
  * ```html
  * <ui-date-picker-input
  *   label="Select date"
+ *   name="birthDate"
  *   placeholder="MM/DD/YYYY"
  *   .value=${new Date()}
+ *   @change=${this.handleDateChange}
+ * ></ui-date-picker-input>
+ * ```
+ *
+ * ### With validation
+ * ```html
+ * <ui-date-picker-input
+ *   label="Birth date"
+ *   name="birthDate"
+ *   required
+ *   .error=${this.hasError}
+ *   .errorMessage=${"Please select a valid date"}
+ *   .minDate=${new Date('1900-01-01')}
+ *   .maxDate=${new Date()}
  * ></ui-date-picker-input>
  * ```
  *
@@ -28,6 +67,14 @@ import '../../md/icons/ui-icon.js'
  *   .dateFormat=${date => date.toLocaleDateString('en-GB')}
  * ></ui-date-picker-input>
  * ```
+ *
+ * ### With disabled dates
+ * ```html
+ * <ui-date-picker-input
+ *   label="Appointment date"
+ *   .disabledDates=${[new Date('2024-12-25'), new Date('2024-01-01')]}
+ * ></ui-date-picker-input>
+ * ```
  */
 @customElement('ui-date-picker-input')
 export class UiDatePickerInput extends LitElement {
@@ -42,6 +89,11 @@ export class UiDatePickerInput extends LitElement {
    */
   @property({ type: String }) accessor label = ''
 
+  /**
+   * The name attribute for the input field (for form handling)
+   */
+  @property({ type: String }) accessor name = ''
+
   /**
    * Placeholder text for the input
    */
@@ -97,106 +149,114 @@ export class UiDatePickerInput extends LitElement {
    */
   @property({ type: Object }) accessor dateFormat: ((date: Date) => string) | undefined = undefined
 
-  @state() private accessor _isOpen = false
+  @state() private accessor isOpen = false
 
-  @state() private accessor _inputValue = ''
+  @state() private accessor inputValue = ''
 
-  @query('ui-outlined-text-field') private accessor _textField!: HTMLElement
+  @query('ui-outlined-text-field') private accessor textField!: HTMLElement
+
+  constructor() {
+    super()
+    // Initialize boolean properties to false as per Lit best practices
+    this.disabled = false
+    this.required = false
+    this.error = false
+  }
 
   override connectedCallback(): void {
     super.connectedCallback()
-    this._updateInputValue()
-    document.addEventListener('click', this._handleDocumentClick.bind(this))
+    this.updateInputValue()
+    document.addEventListener('click', this.handleDocumentClick.bind(this))
   }
 
   override disconnectedCallback(): void {
     super.disconnectedCallback()
-    document.removeEventListener('click', this._handleDocumentClick.bind(this))
+    document.removeEventListener('click', this.handleDocumentClick.bind(this))
   }
 
   override willUpdate(changedProperties: Map<string | number | symbol, unknown>): void {
     if (changedProperties.has('value')) {
-      this._updateInputValue()
+      this.updateInputValue()
     }
   }
 
   override updated(changedProperties: Map<string | number | symbol, unknown>): void {
-    if (changedProperties.has('_isOpen') && this._isOpen) {
+    if (changedProperties.has('isOpen') && this.isOpen) {
       // Set anchor name on text field for CSS Anchor Positioning API
-      if (this._textField) {
+      if (this.textField) {
         // Using setProperty since anchorName is not in TypeScript types yet
-        this._textField.style.setProperty('anchor-name', '--ui-date-picker-anchor')
+        this.textField.style.setProperty('anchor-name', '--ui-date-picker-anchor')
       }
     }
   }
 
-  private _updateInputValue(): void {
+  private updateInputValue(): void {
     if (this.value) {
-      this._inputValue = this.dateFormat ? this.dateFormat(this.value) : formatDate(this.value, this.locale)
+      this.inputValue = this.dateFormat ? this.dateFormat(this.value) : formatDate(this.value, this.locale)
     } else {
-      this._inputValue = ''
+      this.inputValue = ''
     }
   }
 
-  private _handleDocumentClick(event: Event): void {
+  private handleDocumentClick(event: Event): void {
     if (!this.contains(event.target as Node)) {
-      this._isOpen = false
+      this.isOpen = false
     }
   }
 
-  private _handleInputClick(): void {
+  private handleInputClick(): void {
     if (!this.disabled) {
-      this._isOpen = !this._isOpen
+      this.isOpen = !this.isOpen
     }
   }
 
-  private _handleInputChange(event: Event): void {
+  private handleInputChange(event: Event): void {
     const target = event.target as HTMLInputElement
-    this._inputValue = target.value
+    this.inputValue = target.value
 
-    const parsedDate = parseDate(this._inputValue)
+    const parsedDate = parseDate(this.inputValue)
     if (parsedDate) {
       this.value = parsedDate
-      this._dispatchChangeEvent()
+      this.dispatchChangeEvent()
     }
   }
 
-  private _handleCalendarDateSelect(event: CustomEvent<DateSelectEvent>): void {
+  private handleCalendarDateSelect(event: CustomEvent<DateSelectEvent>): void {
     this.value = event.detail.date
-    this._isOpen = false
-    this._dispatchChangeEvent()
+    this.isOpen = false
+    this.dispatchChangeEvent()
   }
 
-  private _handleCalendarDateCancel(): void {
-    this._isOpen = false
+  private handleCalendarDateCancel(): void {
+    this.isOpen = false
   }
 
-  private _handleKeyDown(event: KeyboardEvent): void {
+  private handleKeyDown(event: KeyboardEvent): void {
     switch (event.key) {
       case 'Escape':
-        this._isOpen = false
+        this.isOpen = false
         break
       case 'ArrowDown':
-        if (!this._isOpen) {
+        if (!this.isOpen) {
           event.preventDefault()
-          this._isOpen = true
+          this.isOpen = true
         }
         break
       case 'Enter':
-        if (this._isOpen) {
+        if (this.isOpen) {
           event.preventDefault()
-          this._isOpen = false
+          this.isOpen = false
         }
         break
     }
   }
 
-  private _dispatchChangeEvent(): void {
+  private dispatchChangeEvent(): void {
     this.dispatchEvent(
       new CustomEvent('change', {
         detail: {
           value: this.value,
-          formattedValue: this._inputValue,
+          formattedValue: this.inputValue,
         },
         bubbles: true,
         composed: true,
@@ -204,14 +264,14 @@ export class UiDatePickerInput extends LitElement {
     )
   }
 
-  private _renderCalendarIcon(): TemplateResult {
+  private renderCalendarIcon(): TemplateResult {
     return html`
-      <ui-icon slot="suffix" icon="calendarToday" @click=${this._handleInputClick} style="cursor: pointer;"></ui-icon>
+      <ui-icon slot="suffix" icon="calendarToday" @click=${this.handleInputClick} class="calendar-icon"></ui-icon>
     `
   }
 
-  private _renderDropdown(): TemplateResult | null {
-    if (!this._isOpen) return null
+  private renderDropdown(): TemplateResult | null {
+    if (!this.isOpen) return null
 
     const currentDate = this.value || new Date()
 
@@ -226,8 +286,8 @@ export class UiDatePickerInput extends LitElement {
           .disabledDates=${this.disabledDates}
           .locale=${this.locale}
           showActions
-          @date-select=${this._handleCalendarDateSelect}
-          @date-cancel=${this._handleCalendarDateCancel}
+          @date-select=${this.handleCalendarDateSelect}
+          @date-cancel=${this.handleCalendarDateCancel}
         ></ui-date-picker-calendar>
       </div>
     `
@@ -236,23 +296,24 @@ export class UiDatePickerInput extends LitElement {
   override render(): TemplateResult {
     return html`
       <div class="input-container">
-        ${this._isOpen ? html`<div class="backdrop" @click=${() => (this._isOpen = false)}></div>` : ''}
+        ${this.isOpen ? html`<div class="backdrop" @click=${() => (this.isOpen = false)}></div>` : ''}
         <ui-outlined-text-field
           .label=${this.label}
+          .name=${this.name}
           .placeholder=${this.placeholder}
-          .value=${this._inputValue}
+          .value=${this.inputValue}
           .disabled=${this.disabled}
           .required=${this.required}
-          .errorMessage=${this.errorMessage}
-          .error=${this.error}
+          ?invalid=${this.error}
+          .invalidText=${this.errorMessage}
           readonly
-          @click=${this._handleInputClick}
-          @input=${this._handleInputChange}
-          @keydown=${this._handleKeyDown}
+          @click=${this.handleInputClick}
+          @input=${this.handleInputChange}
+          @keydown=${this.handleKeyDown}
         >
-          ${this._renderCalendarIcon()}
+          ${this.renderCalendarIcon()}
         </ui-outlined-text-field>
-        ${this._renderDropdown()}
+        ${this.renderDropdown()}
       </div>
     `
   }