@oslokommune/punkt-elements 14.0.2 → 14.0.3

package/src/components/datepicker/datepicker-utils.ts

@@ -10,7 +10,17 @@ import { Ref } from 'lit/directives/ref.js'
 import { PktCalendar } from '@/components/calendar/calendar'
 
 /**
- * Utility functions for PktDatepicker
+ * Utility functions for PktDatepicker component
+ *
+ * This module provides helper functions organized by concern:
+ * - valueUtils: Value parsing and validation
+ * - inputTypeUtils: Input type detection
+ * - formUtils: Form submission and validation
+ * - calendarUtils: Calendar interaction and positioning
+ * - eventUtils: Event listener creation
+ * - cssUtils: CSS class generation
+ * - dateProcessingUtils: Date value processing
+ * - keyboardUtils: Keyboard navigation handling
  */
 
 /**
@@ -19,6 +29,19 @@ import { PktCalendar } from '@/components/calendar/calendar'
 export const valueUtils = {
   /**
    * Ensures name attribute ends with [] for multiple/range inputs
+   *
+   * For form submission to work correctly with multiple values,
+   * the input name must end with [] to indicate it's an array.
+   *
+   * @param name - The original name attribute value
+   * @param isMultiple - Whether this is a multiple-date picker
+   * @param isRange - Whether this is a range date picker
+   * @returns The normalized name with [] suffix if needed, or null if name is null
+   *
+   * @example
+   * normalizeNameForMultiple('dates', true, false) // Returns 'dates[]'
+   * normalizeNameForMultiple('dates[]', true, false) // Returns 'dates[]' (no change)
+   * normalizeNameForMultiple('date', false, false) // Returns 'date' (no change)
    */
   normalizeNameForMultiple(
     name: string | null,
@@ -34,6 +57,14 @@ export const valueUtils = {
 
   /**
    * Validates that a range has valid order (start <= end)
+   *
+   * @param values - Array of date strings (ISO format YYYY-MM-DD)
+   * @returns True if range is valid or incomplete, false if end date is before start date
+   *
+   * @example
+   * validateRangeOrder(['2024-01-01', '2024-01-31']) // Returns true
+   * validateRangeOrder(['2024-01-31', '2024-01-01']) // Returns false
+   * validateRangeOrder(['2024-01-01']) // Returns true (incomplete range)
    */
   validateRangeOrder(values: string[]): boolean {
     if (!values || values.length !== 2) return true // Not a complete range
@@ -42,6 +73,13 @@ export const valueUtils = {
 
   /**
    * Sorts date strings chronologically
+   *
+   * @param dates - Array of date strings in ISO format (YYYY-MM-DD)
+   * @returns New array with dates sorted from earliest to latest
+   *
+   * @example
+   * sortDates(['2024-03-15', '2024-01-10', '2024-02-20'])
+   * // Returns ['2024-01-10', '2024-02-20', '2024-03-15']
    */
   sortDates(dates: string[]): string[] {
     return sortDateStrings(dates)
@@ -49,6 +87,28 @@ export const valueUtils = {
 
   /**
    * Filters dates to only include selectable ones based on constraints
+   *
+   * Removes dates that:
+   * - Fall outside the min/max range
+   * - Are in the excludedDates array
+   * - Fall on excluded weekdays (0=Sunday, 6=Saturday)
+   *
+   * @param dates - Array of date strings to filter
+   * @param min - Minimum allowed date (ISO format)
+   * @param max - Maximum allowed date (ISO format)
+   * @param excludedDates - Array of specific dates to exclude
+   * @param excludedWeekdays - Array of weekday numbers to exclude ('0'-'6')
+   * @returns Filtered array containing only selectable dates
+   *
+   * @example
+   * filterSelectableDates(
+   *   ['2024-01-01', '2024-01-06', '2024-01-15'],
+   *   '2024-01-05',
+   *   '2024-01-20',
+   *   ['2024-01-15'],
+   *   ['0', '6'] // Exclude weekends
+   * )
+   * // Returns ['2024-01-06'] (after min, not excluded, not a weekend)
    */
   filterSelectableDates(
     dates: string[],
@@ -67,7 +127,16 @@ export const valueUtils = {
 export const inputTypeUtils = {
   /**
    * Determines the appropriate input type based on device
-   * Mobile Safari does not play well with type="date" amd custom datepickers
+   *
+   * Mobile Safari does not play well with type="date" and custom datepickers,
+   * so we use type="text" on iOS devices to avoid the native date picker
+   * interfering with our custom calendar component.
+   *
+   * @returns 'text' for iOS devices, 'date' for all other devices
+   *
+   * @example
+   * const inputType = getInputType()
+   * // Returns 'text' on iPhone/iPad, 'date' on desktop/Android
    */
   getInputType(): string {
     return isIOS() ? 'text' : 'date'
@@ -80,6 +149,14 @@ export const inputTypeUtils = {
 export const formUtils = {
   /**
    * Submits the form that contains the given element
+   *
+   * Uses ElementInternals API to access the associated form and trigger submission.
+   * Requires the element to have attachInternals() called.
+   *
+   * @param element - The form-associated custom element
+   *
+   * @example
+   * submitForm(this) // From within a custom element
    */
   submitForm(element: HTMLElement): void {
     const form = (element as any).internals?.form as HTMLFormElement
@@ -90,6 +167,18 @@ export const formUtils = {
 
   /**
    * Submits form if available, otherwise executes fallback action
+   *
+   * Useful for Enter key handling where we want to submit the form,
+   * but provide a fallback behavior (like moving focus) if not in a form.
+   *
+   * @param internals - ElementInternals instance with optional form reference
+   * @param fallbackAction - Function to call if no form is available
+   *
+   * @example
+   * submitFormOrFallback(
+   *   this.internals,
+   *   () => this.inputRef.value?.blur()
+   * )
    */
   submitFormOrFallback(internals: any, fallbackAction: () => void): void {
     const form = internals?.form as HTMLFormElement
@@ -102,6 +191,24 @@ export const formUtils = {
 
   /**
    * Validates a date input and sets validity state
+   *
+   * Checks if the input value falls within the min/max range and
+   * sets appropriate validity flags using the ElementInternals API.
+   *
+   * @param input - The input element to validate
+   * @param internals - ElementInternals instance for setting validity
+   * @param min - Minimum allowed date (ISO format)
+   * @param max - Maximum allowed date (ISO format)
+   * @param strings - Optional localized error messages
+   *
+   * @example
+   * validateDateInput(
+   *   inputElement,
+   *   this.internals,
+   *   '2024-01-01',
+   *   '2024-12-31',
+   *   { forms: { messages: { rangeUnderflow: 'Date too early' } } }
+   * )
    */
   validateDateInput(
     input: HTMLInputElement,
@@ -135,6 +242,23 @@ export const formUtils = {
 export const calendarUtils = {
   /**
    * Adds a date to selected dates if it's valid
+   *
+   * Used for multiple date selection - validates the input date against
+   * min/max constraints before adding it to the calendar's selected dates.
+   * Clears the input field after processing.
+   *
+   * @param event - Input or keyboard event containing the target input
+   * @param calendarRef - Lit ref to the calendar component
+   * @param min - Minimum allowed date (ISO format)
+   * @param max - Maximum allowed date (ISO format)
+   *
+   * @example
+   * addToSelected(
+   *   blurEvent,
+   *   this.calendarRef,
+   *   '2024-01-01',
+   *   '2024-12-31'
+   * )
    */
   addToSelected(
     event: Event | KeyboardEvent,
@@ -163,6 +287,25 @@ export const calendarUtils = {
 
   /**
    * Handles calendar positioning based on viewport and input position
+   *
+   * Intelligently positions the calendar popup either above or below the input
+   * depending on available viewport space. Accounts for optional counter elements.
+   *
+   * The positioning logic:
+   * 1. By default, positions calendar below the input (top: 100%)
+   * 2. If calendar would overflow viewport bottom AND there's space above, positions above
+   * 3. Accounts for counter height (30px) when hasCounter is true
+   *
+   * @param popupRef - Lit ref to the calendar popup element
+   * @param inputRef - Lit ref to the input element
+   * @param hasCounter - Whether the input has a character counter below it
+   *
+   * @example
+   * handleCalendarPosition(
+   *   this.popupRef,
+   *   this.inputRef,
+   *   this.multiple && this.maxlength !== null
+   * )
    */
   handleCalendarPosition(
     popupRef: Ref<HTMLDivElement>,
@@ -194,10 +337,34 @@ export const calendarUtils = {
 
 /**
  * Event handling utilities
+ *
+ * Factory functions for creating event listeners with proper closure over component state.
  */
 export const eventUtils = {
   /**
-   * Creates a document click listener for closing calendar
+   * Creates a document click listener for closing calendar on outside clicks
+   *
+   * Returns a function that closes the calendar when clicking outside the
+   * datepicker component (input, button, or calendar popup).
+   *
+   * @param inputRef - Lit ref to the primary input element
+   * @param inputRefTo - Lit ref to the secondary input (for range picker) or null
+   * @param btnRef - Lit ref to the calendar button
+   * @param getCalendarOpen - Function returning current calendar open state
+   * @param onBlur - Callback to execute on blur
+   * @param hideCalendar - Callback to hide the calendar
+   * @returns Event listener function to attach to document
+   *
+   * @example
+   * const listener = createDocumentClickListener(
+   *   this.inputRef,
+   *   null,
+   *   this.btnRef,
+   *   () => this.calendarOpen,
+   *   () => this.handleBlur(),
+   *   () => this.calendarOpen = false
+   * )
+   * document.addEventListener('click', listener)
    */
   createDocumentClickListener(
     inputRef: Ref<HTMLInputElement>,
@@ -225,6 +392,19 @@ export const eventUtils = {
 
   /**
    * Creates a document keydown listener for ESC key
+   *
+   * Returns a function that closes the calendar when Escape is pressed.
+   *
+   * @param getCalendarOpen - Function returning current calendar open state
+   * @param hideCalendar - Callback to hide the calendar
+   * @returns Event listener function to attach to document
+   *
+   * @example
+   * const listener = createDocumentKeydownListener(
+   *   () => this.calendarOpen,
+   *   () => this.calendarOpen = false
+   * )
+   * document.addEventListener('keydown', listener)
    */
   createDocumentKeydownListener(
     getCalendarOpen: () => boolean,
@@ -239,6 +419,22 @@ export const eventUtils = {
 
   /**
    * Handles focus out events for calendar popup
+   *
+   * Closes the calendar when focus leaves the datepicker component entirely.
+   * Used for keyboard navigation accessibility.
+   *
+   * @param event - The focusout event
+   * @param element - The container element to check focus against
+   * @param onBlur - Callback to execute on blur
+   * @param hideCalendar - Callback to hide the calendar
+   *
+   * @example
+   * handleFocusOut(
+   *   event,
+   *   this,
+   *   () => this.handleBlur(),
+   *   () => this.calendarOpen = false
+   * )
    */
   handleFocusOut(
     event: FocusEvent,
@@ -255,10 +451,24 @@ export const eventUtils = {
 
 /**
  * CSS class utilities
+ *
+ * Functions for generating CSS class objects for use with classMap directive.
  */
 export const cssUtils = {
   /**
    * Generates input classes for datepicker
+   *
+   * @param fullwidth - Whether input should take full width
+   * @param showRangeLabels - Whether range labels are visible
+   * @param multiple - Whether this is a multiple date picker
+   * @param range - Whether this is a range date picker
+   * @param readonly - Whether input is readonly
+   * @param inputType - The input type ('date' or 'text')
+   * @returns Object with class names as keys and boolean values
+   *
+   * @example
+   * const classes = getInputClasses(true, false, false, false, false, 'date')
+   * // Returns { 'pkt-input': true, 'pkt-input--fullwidth': true, ... }
    */
   getInputClasses(
     fullwidth: boolean,
@@ -280,7 +490,13 @@ export const cssUtils = {
   },
 
   /**
-   * Generates button classes for datepicker
+   * Generates button classes for calendar button
+   *
+   * @returns Object with class names for the calendar toggle button
+   *
+   * @example
+   * const classes = getButtonClasses()
+   * // Returns { 'pkt-btn': true, 'pkt-btn--icon-only': true, ... }
    */
   getButtonClasses() {
     return {
@@ -294,6 +510,13 @@ export const cssUtils = {
 
   /**
    * Generates range label classes
+   *
+   * @param showRangeLabels - Whether range labels should be visible
+   * @returns Object with class names for range label elements
+   *
+   * @example
+   * const classes = getRangeLabelClasses(true)
+   * // Returns { 'pkt-input-prefix': true, 'pkt-hide': false }
    */
   getRangeLabelClasses(showRangeLabels: boolean) {
     return {
@@ -305,10 +528,24 @@ export const cssUtils = {
 
 /**
  * Date value processing utilities
+ *
+ * Functions for transforming and updating date values between calendar and input elements.
  */
 export const dateProcessingUtils = {
   /**
-   * Handles date selection from calendar events
+   * Processes date selection from calendar events
+   *
+   * Converts the calendar's date selection into the appropriate string format
+   * for the input element's value.
+   *
+   * @param detail - Date selection detail from calendar event (string or array)
+   * @param multiple - Whether this is a multiple date picker
+   * @param range - Whether this is a range date picker
+   * @returns Formatted date string (single date or comma-separated dates)
+   *
+   * @example
+   * processDateSelection(['2024-01-15'], false, false) // Returns '2024-01-15'
+   * processDateSelection(['2024-01-15', '2024-01-20'], true, false) // Returns '2024-01-15,2024-01-20'
    */
   processDateSelection(detail: any, multiple: boolean, range: boolean): string {
     if (!multiple && !range) {
@@ -322,6 +559,30 @@ export const dateProcessingUtils = {
 
   /**
    * Updates input values after calendar selection
+   *
+   * Synchronizes input element values with the calendar's selected dates.
+   * Handles single, range, and multiple date scenarios differently.
+   *
+   * - Single: Updates single input with first date
+   * - Range: Updates two inputs with start and end dates
+   * - Multiple: Does nothing (dates shown as tags, not in input)
+   *
+   * @param inputRef - Lit ref to the primary input element
+   * @param inputRefTo - Lit ref to the secondary input (for range) or null
+   * @param values - Array of selected date strings
+   * @param range - Whether this is a range date picker
+   * @param multiple - Whether this is a multiple date picker
+   * @param manageValidity - Callback to validate the input
+   *
+   * @example
+   * updateInputValues(
+   *   this.inputRef,
+   *   this.inputRefTo,
+   *   ['2024-01-15', '2024-01-20'],
+   *   true, // range
+   *   false,
+   *   (input) => this.dispatchManageValidity(input)
+   * )
    */
   updateInputValues(
     inputRef: Ref<HTMLInputElement>,
@@ -346,6 +607,27 @@ export const dateProcessingUtils = {
 
   /**
    * Processes blur events for range inputs
+   *
+   * Handles the logic when a range input loses focus:
+   * - If input has value: validates it and updates the calendar to reflect the typed date
+   * - If input is empty but range has start date: clears the entire range
+   *
+   * This ensures the range picker calendar stays synchronized when users type dates directly.
+   *
+   * @param event - The blur event from the input
+   * @param values - Current array of selected dates [start, end]
+   * @param calendarRef - Lit ref to the calendar component
+   * @param clearInputValue - Callback to clear the date selection
+   * @param manageValidity - Callback to validate the input
+   *
+   * @example
+   * processRangeBlur(
+   *   blurEvent,
+   *   ['2024-01-15', '2024-01-20'],
+   *   this.calendarRef,
+   *   () => this.value = [],
+   *   (input) => this.dispatchManageValidity(input)
+   * )
    */
   processRangeBlur(
     event: Event,
@@ -359,10 +641,8 @@ export const dateProcessingUtils = {
       manageValidity(target)
       const date = fromISOToDate(target.value)
       if (date) {
-        if (values[0] !== target.value && values[1]) {
-          clearInputValue()
-          calendarRef?.value?.handleDateSelect(date)
-        }
+        // Always update the calendar when a valid date is typed
+        calendarRef?.value?.handleDateSelect(date)
       }
     } else if (values[0]) {
       clearInputValue()
@@ -372,10 +652,47 @@ export const dateProcessingUtils = {
 
 /**
  * Keyboard navigation utilities
+ *
+ * Functions for handling keyboard interactions with proper accessibility support.
  */
 export const keyboardUtils = {
   /**
    * Handles common keyboard interactions for datepicker inputs
+   *
+   * Provides consistent keyboard navigation across all datepicker types:
+   * - Space: Opens calendar
+   * - Enter: Submits form, focuses next input, or blurs (priority order)
+   * - Comma: Adds date to selection (multiple) or blurs input
+   *
+   * The handler prioritizes callbacks in the order provided, allowing
+   * different behaviors for single, multiple, and range pickers.
+   *
+   * @param event - The keyboard event
+   * @param toggleCalendar - Callback to toggle calendar visibility
+   * @param submitForm - Optional callback to submit the form (highest priority on Enter)
+   * @param focusNextInput - Optional callback to focus next input (medium priority on Enter)
+   * @param blurInput - Optional callback to blur current input (lowest priority on Enter/Comma)
+   * @param commaHandler - Optional callback for comma key (overrides default blur behavior)
+   *
+   * @example
+   * // Single datepicker: Enter submits form or blurs
+   * handleInputKeydown(
+   *   event,
+   *   (e) => this.toggleCalendar(e),
+   *   () => formUtils.submitFormOrFallback(this.internals, () => this.inputRef.value?.blur()),
+   *   undefined,
+   *   () => this.inputRef.value?.blur()
+   * )
+   *
+   * @example
+   * // Range datepicker: Enter moves to next input
+   * handleInputKeydown(
+   *   event,
+   *   (e) => this.toggleCalendar(e),
+   *   () => formUtils.submitFormOrFallback(this.internals, () => this.inputRefTo.value?.focus()),
+   *   () => this.inputRefTo.value?.focus(),
+   *   () => this.inputRef.value?.blur()
+   * )
    */
   handleInputKeydown(
     event: KeyboardEvent,
@@ -415,6 +732,18 @@ export const keyboardUtils = {
 
   /**
    * Handles keyboard interactions for calendar button
+   *
+   * Ensures the calendar button is keyboard accessible by responding
+   * to Enter and Space keys (standard button activation keys).
+   *
+   * @param event - The keyboard event
+   * @param toggleCalendar - Callback to toggle calendar visibility
+   *
+   * @example
+   * handleButtonKeydown(
+   *   event,
+   *   (e) => this.dispatchToggleCalendar(e)
+   * )
    */
   handleButtonKeydown(event: KeyboardEvent, toggleCalendar: (e: Event) => void): void {
     const { key } = event

package/src/components/datepicker/datepicker.ts

@@ -347,6 +347,28 @@ export class PktDatepicker extends PktInputElement<Props> {
           }
         }}
         @range-blur=${(e: CustomEvent) => {
+          const inputFrom = this.currentInputElement
+          const inputTo = this.currentInputElementTo
+
+          // Update _value with current input values to sync with calendar
+          if (inputFrom && inputTo) {
+            const fromValue = inputFrom.value
+            const toValue = inputTo.value
+
+            // If from date is after to date, clear the to date
+            if (fromValue && toValue && fromValue > toValue) {
+              inputTo.value = ''
+              this._value = [fromValue]
+              this.value = fromValue
+            } else {
+              const newValues = [fromValue, toValue].filter(Boolean)
+              if (newValues.length > 0 && (newValues[0] !== this._value[0] || newValues[1] !== this._value[1])) {
+                this._value = newValues
+                this.value = newValues.join(',')
+              }
+            }
+          }
+
           dateProcessingUtils.processRangeBlur(
             e.detail.event,
             e.detail.values,
@@ -362,7 +384,9 @@ export class PktDatepicker extends PktInputElement<Props> {
         @handle-date-select=${(e: CustomEvent) => {
           const date = fromISOToDate(e.detail)
           if (date) {
-            if (this._value[1] !== formatISODate(date)) {
+            const formattedDate = formatISODate(date)
+            // Only update calendar if the date is different from current values
+            if (this._value[0] !== formattedDate && this._value[1] !== formattedDate) {
               this.calRef?.value?.handleDateSelect(date)
             }
           }