SolidOS/profile-pane#422 Refactor combobox behaviour

The previous implementation was a bit clunky with the autocomplete and default options list after opening with async options. It also split the concern for watching value changes in two parts (onValueChanged vs willUpdate). This implementation should be more reliable and also supports fallback options and the "change" event.

Author: NoelDeMartin

src/components/combobox/Combobox.ts

@@ -15,11 +15,14 @@ import styles from './Combobox.styles.css'
 class AsyncOptionsInfo extends Error {}
 
 export type ComboboxOptionData = {
-  value: string;
-  label: string | TemplateResult;
+  value: unknown;
+  label: string;
+  template?: TemplateResult;
   selectable?: boolean;
 }
 
+export type ComboboxChangeEvent = CustomEvent<{ option: ComboboxOptionData }>
+
 export type AsyncComboboxOptionsProvider = (query: string) => Promise<ComboboxOptionData[]>
 
 export function defineAsyncComboboxOptionsProvider<T extends AsyncComboboxOptionsProvider> (provider: T): T {
@@ -37,7 +40,7 @@ export default class Combobox extends WebComponent {
   @property({ type: String, reflect: true })
   accessor name = ''
 
-  @property({ type: String })
+  @property()
   accessor value = ''
 
   @property({ type: String, reflect: true })
@@ -64,15 +67,15 @@ export default class Combobox extends WebComponent {
   @property({ type: Function })
   accessor asyncOptionsProvider: AsyncComboboxOptionsProvider | null = null
 
+  @property({ type: Array })
+  accessor optionsFallback: ComboboxOptionData[] | null = null
+
   @query('input')
   private accessor inputElement: HTMLInputElement | null = null
 
   @state()
   private accessor filter = ''
 
-  @state()
-  private accessor debouncedFilter = ''
-
   @state()
   private accessor displayValue = ''
 
@@ -95,29 +98,23 @@ export default class Combobox extends WebComponent {
       new InputTrait(this, {
         getInputElement: () => this.inputElement,
         getInternals: () => this.getInternals(),
-        onValueChanged: (value) => {
-          this.filter = value.toLowerCase()
-          this.displayValue = value
-
-          this.updateFilter(value.toLowerCase())
-
-          const options = this.getFilteredOptions()
-
-          if (options.length === 0) {
-            this.hide()
-            return
-          }
-
-          if (this.open) {
-            this.activeIndex = this.getInitialActiveIndex(options)
-          }
-        },
       })
     )
 
     this.listboxId = `listbox-${this.inputTrait.inputId}`
   }
 
+  get selectedOption (): ComboboxOptionData | undefined {
+    if (!this.value) {
+      return
+    }
+
+    return {
+      label: this.displayValue,
+      value: this.value,
+    }
+  }
+
   disconnectedCallback () {
     super.disconnectedCallback()
 
@@ -127,13 +124,21 @@ export default class Combobox extends WebComponent {
   protected willUpdate (changedProperties: Map<string, unknown>) {
     super.willUpdate(changedProperties)
 
-    if (changedProperties.has('value') && this.displayValue === '') {
-      this.displayValue = this.value
-    }
-
     if (changedProperties.has('asyncOptionsUrl') || changedProperties.has('asyncOptionsProvider')) {
       this.updateAsyncOptionsTask()
     }
+
+    if (changedProperties.has('value')) {
+      const options = this.getFilteredOptions()
+      const option = options.find((option) => option.value === this.value) ?? this.optionsFallback?.find((option) => option.value === this.value)
+      const optionLabel = option?.selectable !== false && option?.label
+
+      this.updateDisplayValue(optionLabel || this.value)
+
+      if (this.open) {
+        this.activeIndex = this.getInitialActiveIndex(options)
+      }
+    }
   }
 
   protected render () {
@@ -176,7 +181,7 @@ export default class Combobox extends WebComponent {
             .value=${this.displayValue}
             @keydown=${this.onInputKeyDown}
             @focus=${this.onInputFocus}
-            @input=${() => this.selectOnly ? this.updateFilter(this.inputElement?.value ?? '') : this.inputTrait.onInput()}
+            @input=${() => this.selectOnly ? this.updateDisplayValue(this.inputElement?.value ?? '') : this.inputTrait.onInput()}
           />
           <icon-lucide-chevron-down></icon-lucide-chevron-down>
         </div>
@@ -201,9 +206,9 @@ export default class Combobox extends WebComponent {
                   data-active=${index === this.activeIndex || nothing}
                   @mousemove=${() => this.setActiveIndex(index)}
                 >
-                  ${option.label}
+                  ${option.template ?? option.label}
                 </div>`
-              : option.label
+              : option.template ?? option.label
           })}
         </div>
       </wa-popup>
@@ -212,12 +217,14 @@ export default class Combobox extends WebComponent {
 
   private getFilteredOptions (): ComboboxOptionData[] {
     if (this.asyncOptionsTask) {
-      const options = this.asyncOptionsTask.render({
+      return this.asyncOptionsTask.render({
+        initial: () => this.optionsFallback ?? [],
         complete: (options) => options,
         pending: () => [
           {
             value: '',
-            label: html`<div class="loading-async-options"><icon-svg-spinners-3-dots-fade></icon-svg-spinners-3-dots-fade></div>`,
+            label: 'Loading...',
+            template: html`<div class="loading-async-options"><icon-svg-spinners-3-dots-fade></icon-svg-spinners-3-dots-fade></div>`,
             selectable: false
           } as const,
         ],
@@ -228,14 +235,13 @@ export default class Combobox extends WebComponent {
           return [
             {
               value: '',
-              label: html`<div class="async-options-message async-options-message--${isError ? 'error' : 'info'}">${message}</div>`,
+              label: message,
+              template: html`<div class="async-options-message async-options-message--${isError ? 'error' : 'info'}">${message}</div>`,
               selectable: false
             } as const,
           ]
         },
       })
-
-      return options ?? []
     }
 
     return this.getOptionsFromDOM().filter((option) =>
@@ -284,13 +290,17 @@ export default class Combobox extends WebComponent {
     this.activeIndex = index
   }
 
-  private updateFilter (value: string, options: { debounce?: boolean } = {}) {
-    this.filter = value.toLowerCase()
+  private updateDisplayValue (value: unknown) {
+    this.displayValue = String(value)
+
+    if (this.open) {
+      const filter = this.displayValue.toLowerCase()
 
-    if (options.debounce ?? true) {
-      this.updateDebouncedFilter(this.filter)
-    } else {
-      this.debouncedFilter = this.filter
+      if (this.asyncOptionsTask) {
+        this.updateDebouncedFilter(filter)
+      } else {
+        this.filter = filter
+      }
     }
   }
 
@@ -333,10 +343,10 @@ export default class Combobox extends WebComponent {
 
         return results.map((result) => ({
           label: String(Object(result)[labelField]),
-          value: String(Object(result)[valueField]),
+          value: Object(result)[valueField],
         }))
       },
-      () => [this.debouncedFilter]
+      () => [this.filter]
     )
   }
 
@@ -365,20 +375,24 @@ export default class Combobox extends WebComponent {
       return
     }
 
+    this.filter = ''
     this.open = false
     this.activeIndex = -1
     this.removeOpenListeners()
-    this.updateFilter('', { debounce: false })
+    this.updateDebouncedFilter.cancel()
   }
 
   private selectOption (option: ComboboxOptionData) {
-    this.inputTrait.setValue(option.value)
+    const previousValue = this.value
 
-    this.displayValue =
-      typeof option.label === 'string' ? option.label : option.value
     this.hide()
+    this.inputTrait.setValue(option.value)
     this.inputElement?.focus({ preventScroll: true })
-    this.dispatchEvent(new Event('change', { bubbles: true, composed: true }))
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, composed: true, detail: { option } }))
+
+    if (previousValue === this.value) {
+      this.updateDisplayValue(option.label)
+    }
   }
 
   private scrollActiveOptionIntoView () {
@@ -442,6 +456,10 @@ export default class Combobox extends WebComponent {
   }
 
   private onAnchorMouseDown (event: MouseEvent) {
+    if (event.target === this.inputElement) {
+      return
+    }
+
     event.preventDefault()
     this.inputElement?.focus({ preventScroll: true })
   }
@@ -500,6 +518,10 @@ export default class Combobox extends WebComponent {
       case 'Tab':
         this.hide()
         break
+      default:
+        if (!this.open) {
+          this.show()
+        }
     }
   }
 

src/components/combobox/index.ts

@@ -1,6 +1,5 @@
-import Combobox, { defineAsyncComboboxOptionsProvider } from './Combobox'
-import type { AsyncComboboxOptionsProvider, ComboboxOptionData } from './Combobox'
+import Combobox from './Combobox'
 
-export { Combobox, defineAsyncComboboxOptionsProvider }
-export type { AsyncComboboxOptionsProvider, ComboboxOptionData }
+export * from './Combobox'
+export { Combobox }
 export default Combobox

src/lib/components/traits/InputTrait.ts

@@ -9,13 +9,12 @@ export type InputTraitTarget = WebComponent & {
   name: string;
   label: string;
   required: boolean;
-  value: string;
+  value: unknown;
 }
 
 export interface InputTraitConfig {
   getInputElement(): HTMLInputElement | HTMLSelectElement | null
   getInternals(): ElementInternals
-  onValueChanged?: (value: string) => void
 }
 
 export default class InputTrait implements WebComponentTrait {
@@ -32,7 +31,7 @@ export default class InputTrait implements WebComponentTrait {
   }
 
   firstUpdated () {
-    this.config.getInternals().setFormValue(this.target.value)
+    this.config.getInternals().setFormValue(String(this.target.value))
     this.updateValidity()
   }
 
@@ -46,7 +45,6 @@ export default class InputTrait implements WebComponentTrait {
     this.target.value = ''
     this.config.getInternals().setFormValue('')
     this.updateValidity()
-    this.config.onValueChanged?.('')
   }
 
   renderLabel () {
@@ -63,12 +61,11 @@ export default class InputTrait implements WebComponentTrait {
     this.config.getInternals().form?.requestSubmit()
   }
 
-  setValue (value: string) {
+  setValue (value: unknown) {
     this.target.value = value
 
-    this.config.getInternals().setFormValue(this.target.value)
+    this.config.getInternals().setFormValue(String(this.target.value))
     this.target.dispatchEvent(new InputEvent('input', { bubbles: true, composed: true }))
-    this.config.onValueChanged?.(this.target.value)
   }
 
   private updateValidity () {