@api-client/ui 0.5.6 → 0.5.8

package/src/md/date-picker/internals/DatePickerCalendar.ts

@@ -11,16 +11,25 @@ import {
   getMonthNames,
   isSameDay,
   formatDate,
+  addDays,
 } from './DatePickerUtils.js'
 import '../../../md/icons/ui-icon.js'
 import '../../../md/button/ui-button.js'
 import '../../../md/icon-button/ui-icon-button.js'
 
+/**
+ * Event dispatched when a single date is selected in immediate mode
+ * or confirmed in pending mode.
+ */
 export interface DateSelectEvent {
   date: Date
   formattedDate: string
 }
 
+/**
+ * Event dispatched when a date range is completed in immediate mode.
+ * Only fired when both start and end dates are selected.
+ */
 export interface DateRangeSelectEvent {
   range: DateRange
   formattedRange: {
@@ -29,6 +38,10 @@ export interface DateRangeSelectEvent {
   }
 }
 
+/**
+ * Event dispatched when a date range selection is confirmed
+ * via the OK button in pending mode.
+ */
 export interface DateRangeConfirmEvent {
   range: DateRange | null
   formattedRange: {
@@ -37,13 +50,31 @@ export interface DateRangeConfirmEvent {
   }
 }
 
+/**
+ * Event dispatched when user cancels a pending selection
+ * via the Cancel button or Escape key.
+ */
 export interface DateCancelEvent {
   reason?: string
 }
 
 /**
  * A calendar grid component for date selection.
- * Supports single date selection and date range selection.
+ * Supports single date selection and date range selection with full keyboard navigation.
+ *
+ * ## Features
+ * - Single date and date range selection
+ * - Keyboard navigation support (arrow keys, home, end, page up/down)
+ * - Configurable date restrictions (min/max dates, disabled dates)
+ * - Localization support for date formatting and month/day names
+ * - Optional action buttons for pending selections
+ * - Accessible design with proper ARIA attributes
+ *
+ * ## Events
+ * - `date-select`: Fired when a single date is selected/confirmed
+ * - `date-range-select`: Fired when a date range is completed (immediate mode)
+ * - `date-range-confirm`: Fired when a date range is confirmed (pending mode)
+ * - `date-cancel`: Fired when a pending selection is cancelled
  *
  * ## Usage
  *
@@ -62,11 +93,24 @@ export interface DateCancelEvent {
  * ### Date range selection
  * ```html
  * <ui-date-picker-calendar
- *   .rangeSelection=${true}
- *   .selectedRange=${{ start: new Date(), end: null }}
+ *   rangeSelection
+ *   .rangeStart=${new Date()}
+ *   .rangeEnd=${null}
  *   @date-range-select=${this.handleRangeSelect}
  * ></ui-date-picker-calendar>
  * ```
+ *
+ * ### With action buttons and restrictions
+ * ```html
+ * <ui-date-picker-calendar
+ *   rangeSelection
+ *   showActions
+ *   .minDate=${new Date()}
+ *   .maxDate=${new Date(Date.now() + 365 * 24 * 60 * 60 * 1000)}
+ *   @date-range-confirm=${this.handleRangeConfirm}
+ *   @date-cancel=${this.handleCancel}
+ * ></ui-date-picker-calendar>
+ * ```
  */
 @customElement('ui-date-picker-calendar')
 export class UiDatePickerCalendar extends LitElement {
@@ -78,99 +122,161 @@ export class UiDatePickerCalendar extends LitElement {
   @property({ type: Number }) accessor year = new Date().getFullYear()
 
   /**
-   * The currently displayed month (0-indexed)
+   * The currently displayed month (0-indexed, where 0 = January)
    */
   @property({ type: Number }) accessor month = new Date().getMonth()
 
   /**
-   * The currently selected date for single selection mode
+   * The currently selected date for single selection mode.
+   * Set to null for no selection.
    */
   @property({ type: Object }) accessor selectedDate: Date | null = null
 
   /**
-   * The selected date range for range selection mode
+   * The start date of the selected range for range selection mode.
+   * Used in combination with rangeEnd to define a date range.
    */
-  @property({ type: Object }) accessor selectedRange: DateRange | null = null
+  @property({ type: Object }) accessor rangeStart: Date | null = null
 
   /**
-   * Enable range selection mode
+   * The end date of the selected range for range selection mode.
+   * Used in combination with rangeStart to define a date range.
+   */
+  @property({ type: Object }) accessor rangeEnd: Date | null = null
+
+  /**
+   * Enable range selection mode. When true, users can select date ranges
+   * instead of single dates. Affects event dispatching and UI behavior.
    */
   @property({ type: Boolean }) accessor rangeSelection = false
 
   /**
-   * Minimum selectable date
+   * Minimum selectable date. Dates before this will be disabled.
+   * Set to undefined for no minimum restriction.
    */
   @property({ type: Object }) accessor minDate: Date | undefined = undefined
 
   /**
-   * Maximum selectable date
+   * Maximum selectable date. Dates after this will be disabled.
+   * Set to undefined for no maximum restriction.
    */
   @property({ type: Object }) accessor maxDate: Date | undefined = undefined
 
   /**
-   * Array of disabled dates
+   * Array of specific dates to disable. These dates will not be selectable
+   * regardless of minDate and maxDate settings.
    */
   @property({ type: Array }) accessor disabledDates: Date[] | undefined = undefined
 
   /**
-   * Locale for date formatting and month/day names
+   * Locale for date formatting and month/day names (e.g., 'en-US', 'fr-FR').
+   * Defaults to browser locale if not specified.
    */
   @property({ type: String }) accessor locale: string | undefined = undefined
 
   /**
-   * Whether to show navigation controls
+   * Whether to show navigation controls (previous/next month and year buttons).
+   * When false, users can only navigate using keyboard or programmatically.
    */
   @property({ type: Boolean }) accessor showNavigation = true
 
   /**
-   * Whether to show action buttons (OK/Cancel)
+   * Whether to show action buttons (OK/Cancel). When true, selections are pending
+   * until confirmed with the OK button. When false, selections are immediate.
    */
   @property({ type: Boolean }) accessor showActions = false
 
   /**
-   * Text for the OK button
+   * Text label for the OK/confirm button. Only visible when showActions is true.
    */
   @property({ type: String }) accessor okButtonText = 'OK'
 
   /**
-   * Text for the Cancel button
+   * Text label for the Cancel button. Only visible when showActions is true.
    */
   @property({ type: String }) accessor cancelButtonText = 'Cancel'
 
-  @state() private accessor _calendarData: CalendarMonth | undefined = undefined
+  @state() private accessor calendarData: CalendarMonth | undefined = undefined
+
+  @state() private accessor monthNames: string[] = []
 
-  @state() private accessor _rangeStart: Date | undefined = undefined
+  @state() private accessor showMonthDropdown = false
 
-  @state() private accessor _monthNames: string[] = []
+  @state() private accessor showYearDropdown = false
 
-  @state() private accessor _showMonthDropdown = false
+  @state() private accessor pendingDate: Date | null = null
 
-  @state() private accessor _showYearDropdown = false
+  @state() private accessor pendingRangeStart: Date | null = null
 
-  @state() private accessor _pendingDate: Date | null = null
+  @state() private accessor pendingRangeEnd: Date | null = null
 
-  @state() private accessor _pendingRange: DateRange | null = null
+  @state() private accessor focusedDate: Date | null = null
 
   override connectedCallback(): void {
     super.connectedCallback()
-    this._updateCalendar()
-    this._updateMonthNames()
-    document.addEventListener('keydown', this._handleDocumentKeyDown.bind(this))
+    this.updateCalendar()
+    this.updateMonthNames()
+    this.initializeFocusedDate()
+  }
+
+  override firstUpdated(): void {
+    // Set initial focus to the calendar container
+    this.updateFocus()
   }
 
   override disconnectedCallback(): void {
     super.disconnectedCallback()
-    document.removeEventListener('keydown', this._handleDocumentKeyDown.bind(this))
+  }
+
+  override willUpdate(changedProperties: Map<string | number | symbol, unknown>): void {
+    if (
+      changedProperties.has('year') ||
+      changedProperties.has('month') ||
+      changedProperties.has('selectedDate') ||
+      changedProperties.has('rangeStart') ||
+      changedProperties.has('rangeEnd') ||
+      changedProperties.has('disabledDates') ||
+      changedProperties.has('locale')
+    ) {
+      this.updateCalendar()
+    }
+
+    if (changedProperties.has('locale')) {
+      this.updateMonthNames()
+    }
+
+    // Update focused date when month/year changes via navigation
+    if (changedProperties.has('year') || changedProperties.has('month')) {
+      this.updateFocusedDateForMonthChange()
+    }
   }
 
   override updated(changedProperties: Map<string | number | symbol, unknown>): void {
-    if (changedProperties.has('_showYearDropdown') && this._showYearDropdown) {
+    if (changedProperties.has('showYearDropdown') && this.showYearDropdown) {
       // Scroll selected year into view
-      this._scrollSelectedYearIntoView()
+      this.scrollSelectedYearIntoView()
+    }
+
+    if (changedProperties.has('focusedDate')) {
+      this.updateFocus()
     }
   }
 
-  private _scrollSelectedYearIntoView(): void {
+  private updateFocus(): void {
+    if (!this.focusedDate) return
+
+    // Find the button for the focused date and set focus
+    const dateString = this.focusedDate.toISOString().split('T')[0]
+    const focusedButton = this.shadowRoot?.querySelector(`[data-date="${dateString}"]`) as HTMLElement
+    if (focusedButton && !focusedButton.hasAttribute('disabled')) {
+      // Use requestAnimationFrame to ensure DOM is updated
+      requestAnimationFrame(() => {
+        focusedButton.focus()
+      })
+    }
+  }
+
+  private scrollSelectedYearIntoView(): void {
     // Wait for next frame to ensure DOM is updated
     requestAnimationFrame(() => {
       const selectedYearButton = this.shadowRoot?.querySelector('.year-option.selected') as HTMLElement
@@ -183,398 +289,526 @@ export class UiDatePickerCalendar extends LitElement {
     })
   }
 
-  override willUpdate(changedProperties: Map<string | number | symbol, unknown>): void {
-    if (
-      changedProperties.has('year') ||
-      changedProperties.has('month') ||
-      changedProperties.has('selectedDate') ||
-      changedProperties.has('selectedRange') ||
-      changedProperties.has('disabledDates') ||
-      changedProperties.has('locale')
-    ) {
-      this._updateCalendar()
+  private updateFocusedDateForMonthChange(): void {
+    if (!this.focusedDate) {
+      this.initializeFocusedDate()
+      return
     }
 
-    if (changedProperties.has('locale')) {
-      this._updateMonthNames()
+    // Keep the same day of month if possible
+    const targetDay = this.focusedDate.getDate()
+    const newDate = new Date(this.year, this.month, targetDay)
+
+    // Check if the target date exists in the new month and is not disabled
+    if (newDate.getMonth() === this.month && !this.isDateDisabled(newDate)) {
+      this.focusedDate = newDate
+    } else {
+      // Find the closest available date
+      this.focusedDate = this.findFirstAvailableDate()
     }
   }
 
-  private _updateCalendar(): void {
-    this._calendarData = generateCalendarMonth(
+  private updateCalendar(): void {
+    const selectedRange = this.rangeStart || this.rangeEnd ? { start: this.rangeStart, end: this.rangeEnd } : null
+    this.calendarData = generateCalendarMonth(
       this.year,
       this.month,
       this.selectedDate,
-      this.selectedRange,
+      selectedRange,
       this.disabledDates,
       this.locale
     )
   }
 
-  private _updateMonthNames(): void {
-    this._monthNames = getMonthNames(this.locale)
+  private updateMonthNames(): void {
+    this.monthNames = getMonthNames(this.locale)
   }
 
-  private _navigateMonth(delta: number): void {
+  private navigateMonth(delta: number): void {
     const newDate = addMonths(new Date(this.year, this.month), delta)
     this.year = newDate.getFullYear()
     this.month = newDate.getMonth()
   }
 
-  private _handlePrevMonth(): void {
-    this._navigateMonth(-1)
+  private handlePrevMonth(): void {
+    this.navigateMonth(-1)
   }
 
-  private _handleNextMonth(): void {
-    this._navigateMonth(1)
+  private handleNextMonth(): void {
+    this.navigateMonth(1)
   }
 
-  private _handlePrevYear(): void {
+  private handlePrevYear(): void {
     this.year = this.year - 1
   }
 
-  private _handleNextYear(): void {
+  private handleNextYear(): void {
     this.year = this.year + 1
   }
 
-  private _handleMonthClick(): void {
-    this._showMonthDropdown = !this._showMonthDropdown
-    this._showYearDropdown = false
+  private handleMonthClick(): void {
+    this.showMonthDropdown = !this.showMonthDropdown
+    this.showYearDropdown = false
   }
 
-  private _handleYearClick(): void {
-    this._showYearDropdown = !this._showYearDropdown
-    this._showMonthDropdown = false
+  private handleYearClick(): void {
+    this.showYearDropdown = !this.showYearDropdown
+    this.showMonthDropdown = false
   }
 
-  private _handleMonthSelect(selectedMonth: number): void {
+  private handleMonthSelect(selectedMonth: number): void {
     this.month = selectedMonth
-    this._showMonthDropdown = false
+    this.showMonthDropdown = false
   }
 
-  private _handleYearSelect(selectedYear: number): void {
+  private handleYearSelect(selectedYear: number): void {
     this.year = selectedYear
-    this._showYearDropdown = false
+    this.showYearDropdown = false
+  }
+
+  private closeDropdowns(): void {
+    this.showMonthDropdown = false
+    this.showYearDropdown = false
+  }
+
+  private navigateDate(delta: number): void {
+    if (!this.focusedDate) return
+
+    const newDate = addDays(this.focusedDate, delta)
+
+    // Check if new date is in current month or if we should navigate to next/previous month
+    if (newDate.getMonth() !== this.month || newDate.getFullYear() !== this.year) {
+      // Navigate to next/previous month
+      if (delta > 0) {
+        this.navigateMonth(1)
+      } else {
+        this.navigateMonth(-1)
+      }
+      // Set focused date to the target date in the new month
+      this.focusedDate = newDate
+      return
+    }
+
+    // Check if new date is disabled
+    if (this.isDateDisabled(newDate)) {
+      // Try to find next available date
+      const availableDate = this.findNextAvailableDate(newDate, delta > 0)
+      if (availableDate) {
+        this.focusedDate = availableDate
+      }
+    } else {
+      this.focusedDate = newDate
+    }
   }
 
-  private _closeDropdowns(): void {
-    this._showMonthDropdown = false
-    this._showYearDropdown = false
+  private findNextAvailableDate(startDate: Date, forward: boolean): Date | null {
+    const direction = forward ? 1 : -1
+    for (let i = 1; i <= 31; i++) {
+      const date = addDays(startDate, i * direction)
+      if (date.getMonth() !== this.month) break // Out of current month
+      if (!this.isDateDisabled(date)) {
+        return date
+      }
+    }
+    return null
   }
 
-  private _handleDocumentKeyDown(event: KeyboardEvent): void {
-    if (event.key === 'Escape') {
-      this._closeDropdowns()
+  private focusFirstDayOfMonth(): void {
+    const firstDay = new Date(this.year, this.month, 1)
+    if (!this.isDateDisabled(firstDay)) {
+      this.focusedDate = firstDay
+    } else {
+      this.focusedDate = this.findFirstAvailableDate()
     }
   }
 
-  private _handleDayClick(day: CalendarDay): void {
+  private focusLastDayOfMonth(): void {
+    const lastDay = new Date(this.year, this.month + 1, 0)
+    if (!this.isDateDisabled(lastDay)) {
+      this.focusedDate = lastDay
+    } else {
+      // Find last available date in month
+      for (let i = lastDay.getDate(); i >= 1; i--) {
+        const date = new Date(this.year, this.month, i)
+        if (!this.isDateDisabled(date)) {
+          this.focusedDate = date
+          break
+        }
+      }
+    }
+  }
+
+  private selectFocusedDate(): void {
+    if (!this.focusedDate || this.isDateDisabled(this.focusedDate)) return
+
+    if (this.rangeSelection) {
+      this.handleRangeSelection(this.focusedDate)
+    } else {
+      this.handleSingleSelection(this.focusedDate)
+    }
+  }
+
+  private handleDayClick(day: CalendarDay): void {
     if (day.isDisabled) return
 
+    // Update focused date to clicked date
+    this.focusedDate = day.date
+
     if (this.rangeSelection) {
-      this._handleRangeSelection(day.date)
+      this.handleRangeSelection(day.date)
     } else {
-      this._handleSingleSelection(day.date)
+      this.handleSingleSelection(day.date)
     }
   }
 
-  private _handleSingleSelection(date: Date): void {
+  private handleSingleSelection(date: Date): void {
     if (this.showActions) {
       // Use pending state when actions are enabled
-      this._pendingDate = date
+      this.pendingDate = date
     } else {
       // Immediate selection when no actions
       this.selectedDate = date
+      this.dispatchDateEvent(date)
+    }
+  }
+
+  private handleRangeSelection(date: Date): void {
+    const isImmediate = !this.showActions
+    const { start, end } = this.getCurrentRange()
+
+    // If we have a complete range, start a new one
+    if (start && end) {
+      this.setRangeValues(date, null, isImmediate)
+      return
+    }
+
+    // If we have a start but no end, complete the range
+    if (start && !end) {
+      const sortedRange = start <= date ? { start, end: date } : { start: date, end: start }
+      this.setRangeValues(sortedRange.start, sortedRange.end, isImmediate)
 
-      const event: DateSelectEvent = {
-        date,
-        formattedDate: formatDate(date, this.locale),
+      if (isImmediate) {
+        this.dispatchRangeEvent(sortedRange)
       }
+      return
+    }
 
-      this.dispatchEvent(
-        new CustomEvent('date-select', {
-          detail: event,
-          bubbles: true,
-          composed: true,
-        })
-      )
+    // Start new range
+    this.setRangeValues(date, null, isImmediate)
+  }
+
+  /**
+   * Helper to get the current range state (either immediate or pending)
+   */
+  private getCurrentRange(): { start: Date | null; end: Date | null } {
+    const isImmediate = !this.showActions
+    return {
+      start: isImmediate ? this.rangeStart : this.pendingRangeStart,
+      end: isImmediate ? this.rangeEnd : this.pendingRangeEnd,
     }
   }
 
-  private _handleRangeSelection(date: Date): void {
-    if (!this._rangeStart || (this.selectedRange?.start && this.selectedRange?.end)) {
-      // Start new range
-      this._rangeStart = date
-      const newRange = { start: date, end: null }
+  /**
+   * Helper to check if we have a complete range in the current mode
+   */
+  private hasCompleteRange(): boolean {
+    const { start, end } = this.getCurrentRange()
+    return !!(start && end)
+  }
 
-      if (this.showActions) {
-        // Use pending state when actions are enabled
-        this._pendingRange = newRange
-      } else {
-        this.selectedRange = newRange
-      }
+  private setRangeValues(start: Date | null, end: Date | null, isImmediate: boolean): void {
+    if (isImmediate) {
+      this.rangeStart = start
+      this.rangeEnd = end
     } else {
-      // Complete range
-      const start = this._rangeStart
-      const end = date
+      this.pendingRangeStart = start
+      this.pendingRangeEnd = end
+    }
+  }
 
-      // Ensure start is before end
-      const sortedRange: DateRange = start <= end ? { start, end } : { start: end, end: start }
+  /**
+   * Helper to dispatch date selection events
+   */
+  private dispatchDateEvent(date: Date): void {
+    const event: DateSelectEvent = {
+      date,
+      formattedDate: formatDate(date, this.locale),
+    }
 
-      this._rangeStart = undefined
+    this.dispatchEvent(
+      new CustomEvent('date-select', {
+        detail: event,
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
 
-      if (this.showActions) {
-        // Use pending state when actions are enabled
-        this._pendingRange = sortedRange
-      } else {
-        // Immediate selection when no actions
-        this.selectedRange = sortedRange
-
-        const event: DateRangeSelectEvent = {
-          range: sortedRange,
-          formattedRange: {
-            start: sortedRange.start ? formatDate(sortedRange.start, this.locale) : null,
-            end: sortedRange.end ? formatDate(sortedRange.end, this.locale) : null,
-          },
-        }
+  /**
+   * Helper to dispatch range selection events
+   */
+  private dispatchRangeEvent(range: { start: Date; end: Date }): void {
+    const event: DateRangeSelectEvent = {
+      range,
+      formattedRange: {
+        start: formatDate(range.start, this.locale),
+        end: formatDate(range.end, this.locale),
+      },
+    }
 
-        this.dispatchEvent(
-          new CustomEvent('date-range-select', {
-            detail: event,
-            bubbles: true,
-            composed: true,
-          })
-        )
-      }
+    this.dispatchEvent(
+      new CustomEvent('date-range-select', {
+        detail: event,
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
+
+  /**
+   * Helper to dispatch range confirmation events
+   */
+  private dispatchRangeConfirmEvent(range: DateRange | null): void {
+    const event: DateRangeConfirmEvent = {
+      range,
+      formattedRange: {
+        start: range?.start ? formatDate(range.start, this.locale) : null,
+        end: range?.end ? formatDate(range.end, this.locale) : null,
+      },
     }
+
+    this.dispatchEvent(
+      new CustomEvent('date-range-confirm', {
+        detail: event,
+        bubbles: true,
+        composed: true,
+      })
+    )
   }
 
-  private _isDateDisabled(date: Date): boolean {
+  /**
+   * Helper to dispatch cancel events
+   */
+  private dispatchCancelEvent(reason = 'user_cancelled'): void {
+    const event: DateCancelEvent = { reason }
+
+    this.dispatchEvent(
+      new CustomEvent('date-cancel', {
+        detail: event,
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
+
+  private isDateDisabled(date: Date): boolean {
     if (this.minDate && date < this.minDate) return true
     if (this.maxDate && date > this.maxDate) return true
     if (this.disabledDates?.some((disabledDate) => isSameDay(date, disabledDate))) return true
     return false
   }
 
-  private _handleConfirm(): void {
+  private handleConfirm(): void {
     if (this.rangeSelection) {
-      if (this._pendingRange) {
-        this.selectedRange = this._pendingRange
-
-        const event: DateRangeConfirmEvent = {
-          range: this._pendingRange,
-          formattedRange: {
-            start: this._pendingRange.start ? formatDate(this._pendingRange.start, this.locale) : null,
-            end: this._pendingRange.end ? formatDate(this._pendingRange.end, this.locale) : null,
-          },
-        }
+      if (this.pendingRangeStart || this.pendingRangeEnd) {
+        this.rangeStart = this.pendingRangeStart
+        this.rangeEnd = this.pendingRangeEnd
+
+        const range = this.rangeStart || this.rangeEnd ? { start: this.rangeStart, end: this.rangeEnd } : null
+
+        // Reset pending state after confirmation
+        this.pendingRangeStart = null
+        this.pendingRangeEnd = null
 
-        this.dispatchEvent(
-          new CustomEvent('date-range-confirm', {
-            detail: event,
-            bubbles: true,
-            composed: true,
-          })
-        )
+        this.dispatchRangeConfirmEvent(range)
       }
     } else {
-      if (this._pendingDate) {
-        this.selectedDate = this._pendingDate
+      if (this.pendingDate) {
+        this.selectedDate = this.pendingDate
 
-        const event: DateSelectEvent = {
-          date: this._pendingDate,
-          formattedDate: formatDate(this._pendingDate, this.locale),
-        }
+        // Reset pending state after confirmation
+        this.pendingDate = null
 
-        this.dispatchEvent(
-          new CustomEvent('date-select', {
-            detail: event,
-            bubbles: true,
-            composed: true,
-          })
-        )
+        this.dispatchDateEvent(this.selectedDate)
       }
     }
   }
 
-  private _handleCancel(): void {
+  private handleCancel(): void {
     // Reset pending state
-    this._pendingDate = null
-    this._pendingRange = null
-    this._rangeStart = undefined
+    this.pendingDate = null
+    this.pendingRangeStart = null
+    this.pendingRangeEnd = null
+
+    this.dispatchCancelEvent()
+  }
 
-    const event: DateCancelEvent = {
-      reason: 'user_cancelled',
+  /**
+   * Helper to render navigation buttons
+   */
+  private renderNavButton(
+    direction: 'prev' | 'next',
+    onClick: () => void,
+    ariaLabel: string,
+    icon: 'chevronLeft' | 'chevronRight'
+  ): TemplateResult | typeof nothing {
+    if (!this.showNavigation || this.showMonthDropdown || this.showYearDropdown) {
+      return nothing
     }
 
-    this.dispatchEvent(
-      new CustomEvent('date-cancel', {
-        detail: event,
-        bubbles: true,
-        composed: true,
-      })
-    )
+    return html`<ui-icon-button
+      class="nav-button"
+      size="xs"
+      @click=${onClick}
+      aria-label=${ariaLabel}
+      title=${ariaLabel}
+    >
+      <ui-icon icon=${icon}></ui-icon>
+    </ui-icon-button>`
   }
 
-  private _renderNavigation(): TemplateResult {
-    const monthName = this._monthNames[this.month] || ''
+  private renderNavigation(): TemplateResult {
+    const monthName = this.monthNames[this.month] || ''
 
     return html`
       <div class="header">
         <div class="month-year">
           <div class="month-selector">
-            ${this.showNavigation && !this._showMonthDropdown && !this._showYearDropdown
-              ? html`
-                  <ui-icon-button
-                    class="nav-button month-nav"
-                    size="xs"
-                    @click=${this._handlePrevMonth}
-                    aria-label="Previous month"
-                    title="Previous month"
-                  >
-                    <ui-icon icon="chevronLeft"></ui-icon>
-                  </ui-icon-button>
-                `
-              : ''}
+            ${this.renderNavButton('prev', this.handlePrevMonth, 'Previous month', 'chevronLeft')}
             <ui-button
               class="month-button"
               color="text"
               size="xs"
-              @click=${this._handleMonthClick}
+              @click=${this.handleMonthClick}
               aria-label="Select month"
-              aria-expanded=${this._showMonthDropdown}
+              aria-expanded=${this.showMonthDropdown}
               trailingIcon
             >
               ${monthName}
               <ui-icon icon="arrowDropDown" slot="icon"></ui-icon>
             </ui-button>
-            ${this.showNavigation && !this._showMonthDropdown && !this._showYearDropdown
-              ? html`
-                  <ui-icon-button
-                    class="nav-button month-nav"
-                    size="xs"
-                    @click=${this._handleNextMonth}
-                    aria-label="Next month"
-                    title="Next month"
-                  >
-                    <ui-icon icon="chevronRight"></ui-icon>
-                  </ui-icon-button>
-                `
-              : ''}
+            ${this.renderNavButton('next', this.handleNextMonth, 'Next month', 'chevronRight')}
           </div>
           <div class="year-selector">
-            ${this.showNavigation && !this._showMonthDropdown && !this._showYearDropdown
-              ? html`
-                  <ui-icon-button
-                    class="nav-button year-nav"
-                    size="xs"
-                    @click=${this._handlePrevYear}
-                    aria-label="Previous year"
-                    title="Previous year"
-                  >
-                    <ui-icon icon="chevronLeft"></ui-icon>
-                  </ui-icon-button>
-                `
-              : ''}
+            ${this.renderNavButton('prev', this.handlePrevYear, 'Previous year', 'chevronLeft')}
             <ui-button
               class="year-button"
               color="text"
               size="xs"
-              @click=${this._handleYearClick}
+              @click=${this.handleYearClick}
               aria-label="Select year"
-              aria-expanded=${this._showYearDropdown}
+              aria-expanded=${this.showYearDropdown}
               trailingIcon
             >
               ${this.year}
               <ui-icon icon="arrowDropDown" slot="icon"></ui-icon>
             </ui-button>
-            ${this.showNavigation && !this._showMonthDropdown && !this._showYearDropdown
-              ? html`
-                  <ui-icon-button
-                    class="nav-button year-nav"
-                    size="xs"
-                    @click=${this._handleNextYear}
-                    aria-label="Next year"
-                    title="Next year"
-                  >
-                    <ui-icon icon="chevronRight"></ui-icon>
-                  </ui-icon-button>
-                `
-              : ''}
+            ${this.renderNavButton('next', this.handleNextYear, 'Next year', 'chevronRight')}
           </div>
         </div>
       </div>
     `
   }
 
-  private _renderWeekdays(): TemplateResult {
-    if (!this._calendarData) return html``
+  private renderWeekdays(): TemplateResult {
+    if (!this.calendarData) return html``
 
     return html`
-      <div class="weekdays">
-        ${this._calendarData.weekdays.map((weekday) => html`<div class="weekday">${weekday}</div>`)}
+      <div class="weekdays" role="row">
+        ${this.calendarData.weekdays.map((weekday) => html`<div class="weekday" role="columnheader">${weekday}</div>`)}
       </div>
     `
   }
 
-  private _renderDay(day: CalendarDay): TemplateResult {
-    const isPendingSelected = this.showActions && this._pendingDate && isSameDay(day.date, this._pendingDate)
-    const isPendingRangeStart =
-      this.showActions && this._pendingRange?.start && isSameDay(day.date, this._pendingRange.start)
-    const isPendingRangeEnd = this.showActions && this._pendingRange?.end && isSameDay(day.date, this._pendingRange.end)
-    const isPendingInRange =
-      this.showActions &&
-      this._pendingRange?.start &&
-      this._pendingRange?.end &&
-      day.date >= this._pendingRange.start &&
-      day.date <= this._pendingRange.end &&
-      !isPendingRangeStart &&
-      !isPendingRangeEnd
-
-    // Determine button color based on selection state
-    let color: 'elevated' | 'filled' | 'outlined' | 'text' | 'tonal' = 'text'
-
+  /**
+   * Helper to determine day selection state for rendering
+   */
+  private getDaySelectionState(day: CalendarDay): {
+    isSelected: boolean
+    isRangeStart: boolean
+    isRangeEnd: boolean
+    isInRange: boolean
+  } {
     if (this.showActions) {
-      if (isPendingRangeStart || isPendingRangeEnd || isPendingSelected) {
-        color = 'filled'
-      } else if (isPendingInRange) {
-        color = 'text'
+      // Use pending state
+      const isPendingSelected = this.pendingDate && isSameDay(day.date, this.pendingDate)
+      const isPendingRangeStart = this.pendingRangeStart && isSameDay(day.date, this.pendingRangeStart)
+      const isPendingRangeEnd = this.pendingRangeEnd && isSameDay(day.date, this.pendingRangeEnd)
+      const isPendingInRange =
+        this.pendingRangeStart &&
+        this.pendingRangeEnd &&
+        day.date >= this.pendingRangeStart &&
+        day.date <= this.pendingRangeEnd &&
+        !isPendingRangeStart &&
+        !isPendingRangeEnd
+
+      return {
+        isSelected: !!isPendingSelected,
+        isRangeStart: !!isPendingRangeStart,
+        isRangeEnd: !!isPendingRangeEnd,
+        isInRange: !!isPendingInRange,
       }
     } else {
-      if (day.isRangeStart || day.isRangeEnd || day.isSelected) {
-        color = 'filled'
-      } else if (day.isInRange) {
-        color = 'text'
+      // Use immediate state
+      return {
+        isSelected: day.isSelected,
+        isRangeStart: day.isRangeStart,
+        isRangeEnd: day.isRangeEnd,
+        isInRange: day.isInRange,
       }
     }
+  }
+
+  /**
+   * Helper to determine button color for a day
+   */
+  private getDayButtonColor(
+    day: CalendarDay,
+    selectionState: ReturnType<typeof this.getDaySelectionState>
+  ): 'elevated' | 'filled' | 'outlined' | 'text' | 'tonal' {
+    if (selectionState.isRangeStart || selectionState.isRangeEnd || selectionState.isSelected) {
+      return 'filled'
+    }
+
+    if (selectionState.isInRange) {
+      return 'text'
+    }
 
-    if (day.isToday && color === 'text') {
-      color = 'outlined'
+    if (day.isToday) {
+      return 'outlined'
     }
 
+    return 'text'
+  }
+
+  private renderDay(day: CalendarDay): TemplateResult {
+    const selectionState = this.getDaySelectionState(day)
+    const color = this.getDayButtonColor(day, selectionState)
+
     const classes = {
       'day-cell': true,
       'other-month': !day.isCurrentMonth,
       'today': day.isToday,
-      'in-range': this.showActions ? !!isPendingInRange : day.isInRange,
-      'range-start': this.showActions ? !!isPendingRangeStart : day.isRangeStart,
-      'range-end': this.showActions ? !!isPendingRangeEnd : day.isRangeEnd,
-      'has-complete-range': this.showActions
-        ? !!(this._pendingRange?.start && this._pendingRange?.end)
-        : !!(this.selectedRange?.start && this.selectedRange?.end),
+      'in-range': selectionState.isInRange,
+      'range-start': selectionState.isRangeStart,
+      'range-end': selectionState.isRangeEnd,
+      'has-complete-range': this.hasCompleteRange(),
     }
 
+    const isFocused = this.focusedDate && isSameDay(day.date, this.focusedDate)
+
     return html`
-      <div class=${classMap(classes)}>
+      <div class=${classMap(classes)} role="gridcell">
         <ui-button
           class="day-button"
           color=${color}
           size="s"
           data-date=${day.date.toISOString().split('T')[0]}
-          tabindex=${day.isToday && !(day.isDisabled || this._isDateDisabled(day.date)) ? '0' : '-1'}
+          tabindex=${isFocused && !(day.isDisabled || this.isDateDisabled(day.date)) ? '0' : '-1'}
           aria-label=${formatDate(day.date, this.locale)}
-          @click=${() => this._handleDayClick(day)}
-          ?disabled=${day.isDisabled || this._isDateDisabled(day.date)}
+          aria-selected=${selectionState.isSelected || selectionState.isRangeStart || selectionState.isRangeEnd}
+          @click=${() => this.handleDayClick(day)}
+          ?disabled=${day.isDisabled || this.isDateDisabled(day.date)}
         >
           ${day.date.getDate()}
         </ui-button>
@@ -582,50 +816,63 @@ export class UiDatePickerCalendar extends LitElement {
     `
   }
 
-  private _renderDays(): TemplateResult {
-    if (!this._calendarData) return html``
+  private renderDays(): TemplateResult {
+    if (!this.calendarData) return html``
 
-    return html`<div class="days">${this._calendarData.days.map((day) => this._renderDay(day))}</div>`
+    return html`<div class="days">${this.calendarData.days.map((day) => this.renderDay(day))}</div>`
   }
 
-  private _renderActions(): TemplateResult | typeof nothing {
+  private renderActions(): TemplateResult | typeof nothing {
     if (!this.showActions) return nothing
 
-    const hasSelection = this.rangeSelection ? this._pendingRange?.start : this._pendingDate
+    const hasSelection = this.rangeSelection ? this.pendingRangeStart : this.pendingDate
 
     return html`
       <div class="actions">
-        <ui-button size="s" color="text" @click=${this._handleCancel}>${this.cancelButtonText}</ui-button>
-        <ui-button size="s" color="text" @click=${this._handleConfirm} ?disabled=${!hasSelection}>
+        <ui-button size="s" color="text" @click=${this.handleCancel}>${this.cancelButtonText}</ui-button>
+        <ui-button size="s" color="text" @click=${this.handleConfirm} ?disabled=${!hasSelection}>
           ${this.okButtonText}
         </ui-button>
       </div>
     `
   }
 
-  private _renderMonthDropdown(): TemplateResult {
+  /**
+   * Helper to render dropdown option buttons
+   */
+  private renderDropdownOption(
+    value: string | number,
+    label: string,
+    isSelected: boolean,
+    onClick: () => void,
+    className = ''
+  ): TemplateResult {
+    return html`
+      <ui-button
+        class="dropdown-option ${className} ${isSelected ? 'selected' : ''}"
+        color=${isSelected ? 'filled' : 'text'}
+        size="s"
+        @click=${onClick}
+        aria-label=${label}
+      >
+        ${label}
+      </ui-button>
+    `
+  }
+
+  private renderMonthDropdown(): TemplateResult {
     return html`
       <div class="dropdown-view">
         <div class="month-list">
-          ${this._monthNames.map(
-            (monthName, index) => html`
-              <ui-button
-                class="month-option ${index === this.month ? 'selected' : ''}"
-                color=${index === this.month ? 'filled' : 'text'}
-                size="s"
-                @click=${() => this._handleMonthSelect(index)}
-                aria-label=${monthName}
-              >
-                ${monthName}
-              </ui-button>
-            `
+          ${this.monthNames.map((monthName, index) =>
+            this.renderDropdownOption(index, monthName, index === this.month, () => this.handleMonthSelect(index))
           )}
         </div>
       </div>
     `
   }
 
-  private _renderYearDropdown(): TemplateResult {
+  private renderYearDropdown(): TemplateResult {
     const currentYear = this.year
     const startYear = currentYear - 50
     const endYear = currentYear + 50
@@ -638,46 +885,133 @@ export class UiDatePickerCalendar extends LitElement {
     return html`
       <div class="dropdown-view">
         <div class="year-grid">
-          ${years.map(
-            (year) => html`
-              <ui-button
-                class="year-option ${year === this.year ? 'selected' : ''}"
-                color=${year === this.year ? 'filled' : 'text'}
-                size="s"
-                @click=${() => this._handleYearSelect(year)}
-                aria-label=${year.toString()}
-              >
-                ${year}
-              </ui-button>
-            `
+          ${years.map((year) =>
+            this.renderDropdownOption(
+              year,
+              year.toString(),
+              year === this.year,
+              () => this.handleYearSelect(year),
+              'year-option'
+            )
           )}
         </div>
       </div>
     `
   }
 
+  private findFirstAvailableDate(): Date {
+    const firstDayOfMonth = new Date(this.year, this.month, 1)
+    for (let i = 0; i < 31; i++) {
+      const date = addDays(firstDayOfMonth, i)
+      if (date.getMonth() !== this.month) break // Next month
+      if (!this.isDateDisabled(date)) {
+        return date
+      }
+    }
+    return firstDayOfMonth // Fallback
+  }
+
+  private handleKeyDown(event: KeyboardEvent): void {
+    // Prevent default behavior for navigation keys
+    const navigationKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown', ' ']
+    if (navigationKeys.includes(event.key)) {
+      event.preventDefault()
+    }
+
+    switch (event.key) {
+      case 'ArrowLeft':
+        this.navigateDate(-1)
+        break
+      case 'ArrowRight':
+        this.navigateDate(1)
+        break
+      case 'ArrowUp':
+        this.navigateDate(-7)
+        break
+      case 'ArrowDown':
+        this.navigateDate(7)
+        break
+      case 'Enter':
+      case ' ':
+        this.selectFocusedDate()
+        break
+      case 'Home':
+        this.focusFirstDayOfMonth()
+        break
+      case 'End':
+        this.focusLastDayOfMonth()
+        break
+      case 'PageUp':
+        if (event.shiftKey) {
+          this.handlePrevYear()
+        } else {
+          this.navigateMonth(-1)
+        }
+        break
+      case 'PageDown':
+        if (event.shiftKey) {
+          this.handleNextYear()
+        } else {
+          this.navigateMonth(1)
+        }
+        break
+      case 'Escape':
+        this.closeDropdowns()
+        break
+    }
+  }
+
+  /**
+   * Helper to check if a date is in the current month and not disabled
+   */
+  private isDateAvailable(date: Date): boolean {
+    return date.getMonth() === this.month && date.getFullYear() === this.year && !this.isDateDisabled(date)
+  }
+
+  private initializeFocusedDate(): void {
+    // Priority: selectedDate, rangeStart, today, first available date
+    const candidates = [this.selectedDate, this.rangeStart, new Date()].filter(Boolean) as Date[]
+
+    for (const candidate of candidates) {
+      if (this.isDateAvailable(candidate)) {
+        this.focusedDate = candidate
+        return
+      }
+    }
+
+    // Fallback to first available date in current month
+    this.focusedDate = this.findFirstAvailableDate()
+  }
+
   override render(): TemplateResult {
     // Show dropdown views instead of calendar when dropdowns are open
-    if (this._showMonthDropdown) {
+    if (this.showMonthDropdown) {
       return html`
-        <div class="calendar" role="grid" aria-label="Calendar">
-          ${this._renderNavigation()} ${this._renderMonthDropdown()}
+        <div class="calendar" role="grid" aria-label="Month selection for ${this.year}">
+          ${this.renderNavigation()} ${this.renderMonthDropdown()}
         </div>
       `
     }
 
-    if (this._showYearDropdown) {
+    if (this.showYearDropdown) {
       return html`
-        <div class="calendar" role="grid" aria-label="Calendar">
-          ${this._renderNavigation()} ${this._renderYearDropdown()}
+        <div class="calendar" role="grid" aria-label="Year selection">
+          ${this.renderNavigation()} ${this.renderYearDropdown()}
         </div>
       `
     }
 
     // Default calendar view
     return html`
-      <div class="calendar" role="grid" aria-label="Calendar">
-        ${this._renderNavigation()} ${this._renderWeekdays()} ${this._renderDays()} ${this._renderActions()}
+      <div
+        class="calendar"
+        role="grid"
+        aria-label="Calendar for ${this.monthNames[this.month]} ${this.year}"
+        aria-roledescription="Calendar grid"
+        tabindex="0"
+        @keydown=${this.handleKeyDown}
+      >
+        ${this.renderNavigation()} ${this.renderWeekdays()} ${this.renderDays()} ${this.renderActions()}
       </div>
     `
   }