tam_select 1.1.1 → 1.2.3

data/src/tam-select.js

@@ -1,18 +1,29 @@
 const DEFAULT_CLASSES = {
-  wrapper: "tam-select relative w-full",
-  control: "flex min-h-10 w-full cursor-text flex-wrap items-center gap-1.5 rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 shadow-sm transition focus-within:border-blue-500 focus-within:ring-2 focus-within:ring-blue-500/20 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100",
-  controlDisabled: "cursor-not-allowed bg-zinc-100 opacity-60 dark:bg-zinc-800",
-  input: "min-w-16 flex-1 border-0 bg-transparent p-0 text-sm text-zinc-900 outline-none placeholder:text-zinc-400 focus:ring-0 dark:text-zinc-100 dark:placeholder:text-zinc-500",
+  wrapper: "tam-select relative w-full text-zinc-900 [color-scheme:light] dark:text-zinc-100 dark:[color-scheme:dark]",
+  control: "relative flex min-h-11 w-full cursor-text flex-wrap items-center gap-2 rounded-xl border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 shadow-sm transition duration-150 hover:border-zinc-400 focus-within:border-blue-500 focus-within:ring-4 focus-within:ring-blue-500/10 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100 dark:shadow-black/20 dark:hover:border-zinc-600 dark:focus-within:border-blue-400 dark:focus-within:ring-blue-400/10",
+  controlOpen: "border-blue-500 ring-4 ring-blue-500/10 dark:border-blue-400 dark:ring-blue-400/10",
+  controlInvalid: "border-red-500 ring-4 ring-red-500/10 dark:border-red-400 dark:ring-red-400/10",
+  controlDisabled: "cursor-not-allowed bg-zinc-100 opacity-60 dark:bg-zinc-800 dark:text-zinc-400",
+  input: "min-w-16 flex-1 border-0 bg-transparent p-0 text-left text-sm text-zinc-900 outline-none placeholder:text-zinc-400 focus:ring-0 dark:text-zinc-100 dark:placeholder:text-zinc-500",
+  inputClosed: "absolute inset-0 z-0 h-full w-full cursor-pointer opacity-0",
+  trigger: "absolute inset-0 z-0 h-full w-full cursor-pointer rounded-xl border-0 bg-transparent p-0 focus:outline-none disabled:cursor-not-allowed",
+  searchIcon: "size-4 shrink-0 text-zinc-400 dark:text-zinc-500",
   placeholder: "pointer-events-none text-zinc-400 dark:text-zinc-500",
-  tag: "inline-flex max-w-full items-center gap-1 rounded-md bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-200 dark:bg-blue-950/50 dark:text-blue-300 dark:ring-blue-800",
+  tag: "relative z-10 inline-flex max-w-full items-center gap-1 rounded-lg bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-200 transition-colors dark:bg-blue-950/50 dark:text-blue-300 dark:ring-blue-800",
   tagRemove: "rounded p-0.5 hover:bg-blue-100 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:hover:bg-blue-900",
-  clear: "ml-auto rounded p-1 text-zinc-400 hover:bg-zinc-100 hover:text-zinc-700 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:hover:bg-zinc-800 dark:hover:text-zinc-200",
-  chevron: "ml-1 size-4 shrink-0 text-zinc-400 transition-transform",
+  clear: "relative z-20 ml-auto rounded p-1 text-zinc-400 transition-colors hover:bg-zinc-100 hover:text-zinc-700 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:text-zinc-500 dark:hover:bg-zinc-800 dark:hover:text-zinc-200 dark:focus:ring-blue-400",
+  chevron: "pointer-events-none relative z-10 ml-1 size-4 shrink-0 text-zinc-400 transition-transform",
   chevronOpen: "rotate-180",
-  dropdown: "absolute z-50 mt-1 max-h-72 w-full overflow-auto rounded-lg border border-zinc-200 bg-white p-1 shadow-xl ring-1 ring-black/5 dark:border-zinc-700 dark:bg-zinc-900",
-  option: "flex cursor-pointer items-center justify-between gap-3 rounded-md px-3 py-2 text-sm text-zinc-700 outline-none dark:text-zinc-200",
-  optionActive: "bg-zinc-100 dark:bg-zinc-800",
-  optionSelected: "bg-blue-50 font-medium text-blue-700 dark:bg-blue-950/50 dark:text-blue-300",
+  dropdown: "absolute z-50 mt-1.5 max-h-72 w-full origin-top overflow-auto rounded-xl border border-zinc-200 bg-white p-1.5 shadow-2xl ring-1 ring-black/5 dark:border-zinc-700 dark:bg-zinc-900 dark:shadow-black/50 dark:ring-white/10",
+  option: "flex min-h-11 cursor-pointer items-center justify-between gap-3 rounded-lg px-3 py-2 text-sm text-zinc-700 outline-none transition-colors duration-100 dark:text-zinc-200",
+  optionContent: "flex min-w-0 flex-1 items-center gap-3",
+  optionText: "flex min-w-0 flex-1 flex-col",
+  optionLabel: "font-normal",
+  optionDetail: "text-xs font-normal text-zinc-500 dark:text-zinc-400",
+  optionImage: "size-9 shrink-0 rounded-full bg-zinc-100 object-cover dark:bg-zinc-800",
+  optionMeta: "shrink-0 rounded bg-zinc-100 px-1.5 py-0.5 text-xs font-medium text-zinc-600 dark:bg-zinc-800 dark:text-zinc-300",
+  optionActive: "bg-blue-600 text-white shadow-sm [&_*]:text-white dark:bg-blue-500 dark:text-white",
+  optionSelected: "bg-blue-50 font-medium text-blue-700 dark:bg-blue-950/60 dark:text-blue-300",
   optionDisabled: "cursor-not-allowed opacity-50",
   message: "px-3 py-6 text-center text-sm text-zinc-500 dark:text-zinc-400",
   spinner: "size-4 animate-spin rounded-full border-2 border-zinc-300 border-t-blue-600",
@@ -20,16 +31,18 @@ const DEFAULT_CLASSES = {
 }
 
 const ICONS = {
+  search: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" d="m14.5 14.5 3 3m-1.25-8.25a7 7 0 1 1-14 0 7 7 0 0 1 14 0Z"/></svg>',
   chevron: '<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" d="M5.22 7.22a.75.75 0 011.06 0L10 10.94l3.72-3.72a.75.75 0 111.06 1.06l-4.25 4.25a.75.75 0 01-1.06 0L5.22 8.28a.75.75 0 010-1.06z" clip-rule="evenodd"/></svg>',
   close: '<svg viewBox="0 0 20 20" fill="currentColor" class="size-3" aria-hidden="true"><path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z"/></svg>',
   check: '<svg viewBox="0 0 20 20" fill="currentColor" class="size-4" aria-hidden="true"><path fill-rule="evenodd" d="M16.7 5.3a1 1 0 010 1.4l-8 8a1 1 0 01-1.4 0l-4-4a1 1 0 011.4-1.4L8 12.6l7.3-7.3a1 1 0 011.4 0z" clip-rule="evenodd"/></svg>'
 }
 
 const uid = () => `tam-select-${Math.random().toString(36).slice(2, 10)}`
-const normalize = value => String(value ?? "").normalize("NFKD").toLocaleLowerCase()
+const normalize = value => String(value ?? "").normalize("NFKD").replace(/\p{Mark}/gu, "").toLocaleLowerCase().trim()
 const toggleClasses = (element, classNames, force) => {
   String(classNames).split(/\s+/).filter(Boolean).forEach(className => element.classList.toggle(className, force))
 }
+const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key)
 
 export class TamSelect {
   static instances = new WeakMap()
@@ -54,6 +67,7 @@ export class TamSelect {
       createText: query => `Create “${query}”`,
       loadingText: "Loading…",
       loadMoreText: "Load more",
+      inputTooShortText: remaining => `Enter ${remaining} more character${remaining === 1 ? "" : "s"}`,
       remoteUrl: null,
       queryParam: "q",
       pageParam: "page",
@@ -61,25 +75,38 @@ export class TamSelect {
       minQueryLength: 0,
       valueField: "value",
       labelField: "label",
+      imageField: "image",
       itemsPath: "items",
       paginationPath: "pagination",
+      matcher: null,
       classes: {},
       headers: {},
       ...options
     }
     this.classes = { ...DEFAULT_CLASSES, ...this.options.classes }
     this.multiple = select.multiple
+    this.searchable = Boolean(this.options.searchable || this.options.creatable)
     this.items = []
-    this.filtered = []
+    this.remoteResults = []
+    this.visibleItems = []
     this.activeIndex = -1
     this.opened = false
     this.loading = false
+    this.loadingPage = null
     this.error = null
     this.query = ""
-    this.page = 1
+    this.page = 0
+    this.nextPage = null
     this.hasMore = false
-    this.abortController = null
+    this.requestSequence = 0
+    this.activeRequest = null
+    this.optionIds = new WeakMap()
+    this.optionIdSequence = 0
+    this.invalidFromEvent = false
     this.originalTabIndex = select.getAttribute("tabindex")
+    this.originalAriaHidden = select.getAttribute("aria-hidden")
+    this.originalId = select.getAttribute("id")
+    this.hadSrOnlyClass = select.classList.contains("sr-only")
     this.build()
     this.bind()
     this.readNativeOptions()
@@ -91,31 +118,49 @@ export class TamSelect {
     this.id = this.select.id || uid()
     if (!this.select.id) this.select.id = this.id
     this.listboxId = `${this.id}-listbox`
+    this.valuesId = `${this.id}-value`
     this.select.classList.add("sr-only")
     this.select.tabIndex = -1
+    this.select.setAttribute("aria-hidden", "true")
 
     this.wrapper = document.createElement("div")
     this.wrapper.className = this.classes.wrapper
     this.wrapper.dataset.tamSelectRoot = ""
+
     this.control = document.createElement("div")
     this.control.className = this.classes.control
-    this.control.setAttribute("role", "combobox")
-    this.control.setAttribute("aria-haspopup", "listbox")
-    this.control.setAttribute("aria-expanded", "false")
-    this.control.setAttribute("aria-controls", this.listboxId)
-    this.control.tabIndex = this.select.disabled ? -1 : 0
 
     this.values = document.createElement("div")
+    this.values.id = this.valuesId
     this.values.className = "contents"
-    this.input = document.createElement("input")
-    this.input.type = "text"
-    this.input.className = this.classes.input
-    this.input.placeholder = this.options.searchable ? this.options.searchPlaceholder : ""
-    this.input.autocomplete = "off"
-    this.input.spellcheck = false
-    this.input.setAttribute("aria-autocomplete", "list")
-    this.input.setAttribute("aria-controls", this.listboxId)
-    if (!this.options.searchable) this.input.readOnly = true
+
+    this.searchIcon = document.createElement("span")
+    this.searchIcon.className = this.classes.searchIcon
+    this.searchIcon.innerHTML = ICONS.search
+
+    if (this.searchable) {
+      this.input = document.createElement("input")
+      this.input.id = `${this.id}-search`
+      this.input.type = "text"
+      this.input.className = this.classes.input
+      this.input.autocomplete = "off"
+      this.input.spellcheck = false
+      this.input.setAttribute("role", "combobox")
+      this.input.setAttribute("aria-haspopup", "listbox")
+      this.input.setAttribute("aria-expanded", "false")
+      this.input.setAttribute("aria-controls", this.listboxId)
+      this.input.setAttribute("aria-autocomplete", "list")
+      this.focusTarget = this.input
+    } else {
+      this.trigger = document.createElement("button")
+      this.trigger.type = "button"
+      this.trigger.className = this.classes.trigger
+      this.trigger.setAttribute("role", "combobox")
+      this.trigger.setAttribute("aria-haspopup", "listbox")
+      this.trigger.setAttribute("aria-expanded", "false")
+      this.trigger.setAttribute("aria-controls", this.listboxId)
+      this.focusTarget = this.trigger
+    }
 
     this.clearButton = document.createElement("button")
     this.clearButton.type = "button"
@@ -126,78 +171,183 @@ export class TamSelect {
     this.chevron = document.createElement("span")
     this.chevron.className = this.classes.chevron
     this.chevron.innerHTML = ICONS.chevron
+
     this.dropdown = document.createElement("div")
     this.dropdown.id = this.listboxId
     this.dropdown.className = `${this.classes.dropdown} hidden`
     this.dropdown.setAttribute("role", "listbox")
     if (this.multiple) this.dropdown.setAttribute("aria-multiselectable", "true")
 
-    this.control.append(this.values, this.input, this.clearButton, this.chevron)
+    const focusControl = this.searchable ? [this.searchIcon, this.input] : [this.trigger]
+    this.control.append(this.values, ...focusControl, this.clearButton, this.chevron)
     this.wrapper.append(this.control, this.dropdown)
     this.select.after(this.wrapper)
+    this.labelElements = this.findLabelElements()
     this.applyDisabled()
+    this.syncAria()
   }
 
   bind() {
     this.onControlClick = event => {
-      if (this.select.disabled || event.target.closest("button")) return
+      if (!this.searchable || this.select.disabled || event.target.closest("button")) return
       this.open()
       this.input.focus()
     }
     this.onInput = () => {
       this.query = this.input.value
-      this.page = 1
-      this.open()
+      this.open(false)
       if (this.options.remoteUrl) this.scheduleRemote()
       else this.filterLocal()
     }
     this.onKeydown = event => this.handleKeydown(event)
     this.onClear = event => { event.stopPropagation(); this.clear() }
+    this.onTrigger = event => { event.preventDefault(); this.open(); this.trigger.focus() }
     this.onOutside = event => { if (!this.wrapper.contains(event.target)) this.close() }
-    this.onNativeChange = () => { this.readNativeOptions(); this.renderSelection(); this.renderDropdown() }
+    this.onNativeChange = () => {
+      if (this.select.checkValidity()) this.invalidFromEvent = false
+      this.readNativeOptions()
+      this.renderSelection()
+      this.syncAria()
+      this.renderDropdown()
+    }
+    this.onNativeInvalid = event => {
+      event.preventDefault()
+      this.invalidFromEvent = true
+      this.syncAria()
+      this.focusTarget.focus()
+    }
     this.onScroll = () => {
       if (!this.options.remoteUrl || !this.hasMore || this.loading) return
-      if (this.dropdown.scrollTop + this.dropdown.clientHeight >= this.dropdown.scrollHeight - 32) this.loadRemote(this.page + 1, true)
+      if (this.dropdown.scrollTop + this.dropdown.clientHeight >= this.dropdown.scrollHeight - 32) {
+        this.loadRemote(this.nextPage || this.page + 1, true)
+      }
+    }
+    this.onLabelClick = event => {
+      if (event.target.closest("a, button, input, select, textarea")) return
+      event.preventDefault()
+      this.focusTarget.focus()
     }
+
     this.control.addEventListener("click", this.onControlClick)
-    this.input.addEventListener("input", this.onInput)
-    this.control.addEventListener("keydown", this.onKeydown)
+    this.focusTarget.addEventListener("keydown", this.onKeydown)
+    if (this.input) this.input.addEventListener("input", this.onInput)
+    if (this.trigger) this.trigger.addEventListener("click", this.onTrigger)
     this.clearButton.addEventListener("click", this.onClear)
     this.dropdown.addEventListener("scroll", this.onScroll)
     this.select.addEventListener("change", this.onNativeChange)
+    this.select.addEventListener("invalid", this.onNativeInvalid)
+    this.labelElements.forEach(label => label.addEventListener("click", this.onLabelClick))
     document.addEventListener("pointerdown", this.onOutside)
   }
 
+  findLabelElements() {
+    const labels = Array.from(document.querySelectorAll("label")).filter(label => label.htmlFor === this.id || label.contains(this.select))
+    return [...new Set(labels)]
+  }
+
+  labelledBy() {
+    const nativeLabelledBy = this.select.getAttribute("aria-labelledby")
+    if (nativeLabelledBy) return nativeLabelledBy
+    if (!this.labelElements.length) return null
+    return this.labelElements.map(label => {
+      if (!label.id) label.id = uid()
+      return label.id
+    }).join(" ")
+  }
+
   readNativeOptions() {
+    const previousItems = new Map(this.items.map(item => [item.option, item]))
     this.items = Array.from(this.select.options)
-      .filter(option => option.value !== "" || option.selected)
-      .map(option => ({ value: option.value, label: option.textContent.trim(), disabled: option.disabled, selected: option.selected, option }))
-    this.filterLocal(false)
+      .filter(option => option.value !== "")
+      .map(option => {
+        const item = previousItems.get(option) || { option, id: this.optionId(option) }
+        Object.assign(item, {
+          value: option.value,
+          label: option.textContent.trim(),
+          detail: option.dataset.detail || null,
+          meta: option.dataset.meta || null,
+          image: option.dataset.image || null,
+          disabled: option.disabled,
+          selected: option.selected,
+          option
+        })
+        return item
+      })
+
+    if (this.options.remoteUrl) {
+      const currentOptions = new Set(this.items.map(item => item.option))
+      this.remoteResults = this.remoteResults.filter(item => currentOptions.has(item.option))
+      this.updateVisibleItems(this.remoteResults)
+    } else {
+      this.filterLocal(false)
+    }
   }
 
-  selectedItems() { return this.items.filter(item => item.option?.selected || item.selected) }
+  selectedItems() {
+    return this.items.filter(item => item.option?.selected || item.selected)
+  }
+
+  matchesLocalItem(item) {
+    if (typeof this.options.matcher === "function") return Boolean(this.options.matcher(item, this.query))
+    const terms = normalize(this.query).split(/\s+/).filter(Boolean)
+    if (!terms.length) return true
+    const searchableText = normalize([item.label, item.detail, item.meta].filter(Boolean).join(" "))
+    return terms.every(term => searchableText.includes(term))
+  }
 
   filterLocal(render = true) {
-    const needle = normalize(this.query)
-    this.filtered = this.items.filter(item => !needle || normalize(item.label).includes(needle))
-    this.activeIndex = this.filtered.findIndex(item => !item.disabled)
+    this.updateVisibleItems(this.items.filter(item => this.matchesLocalItem(item)))
     if (render) this.renderDropdown()
   }
 
+  updateVisibleItems(candidateItems, preserveActive = true) {
+    const previousId = preserveActive ? this.visibleItems[this.activeIndex]?.id : null
+    const entries = candidateItems
+      .filter(item => this.multiple || !item.selected)
+      .map(item => ({ type: "item", id: item.id, item, disabled: Boolean(item.disabled) }))
+
+    const createEntry = this.createEntry()
+    if (createEntry) entries.push(createEntry)
+
+    this.visibleItems = entries
+    const preservedIndex = previousId ? entries.findIndex(entry => entry.id === previousId && !entry.disabled) : -1
+    this.activeIndex = preservedIndex >= 0 ? preservedIndex : entries.findIndex(entry => !entry.disabled)
+  }
+
+  createEntry() {
+    const label = this.query.trim()
+    if (!this.options.creatable || !label) return null
+    const value = typeof this.options.createValue === "function" ? this.options.createValue(label) : label
+    const normalizedValue = normalize(value)
+    const normalizedLabel = normalize(label)
+    const duplicate = this.items.some(item => normalize(item.value) === normalizedValue || normalize(item.label) === normalizedLabel)
+    if (!normalizedValue || duplicate) return null
+    return { type: "create", id: `${this.listboxId}-create`, label, value: String(value), disabled: false }
+  }
+
   renderSelection() {
     const selected = this.selectedItems()
     this.values.replaceChildren()
-    if (this.multiple) selected.forEach(item => this.values.append(this.makeTag(item)))
-    else if (selected.length) {
-      const label = document.createElement("span")
-      label.className = "min-w-0 flex-1 truncate"
-      label.textContent = selected[0].label
-      this.values.append(label)
+    if (this.multiple) {
+      selected.forEach(item => this.values.append(this.makeTag(item)))
+    } else if (selected.length) {
+      this.values.append(this.makeItemContent(selected[0], true))
+    } else {
+      const placeholder = document.createElement("span")
+      placeholder.className = this.classes.placeholder
+      placeholder.textContent = this.options.placeholder
+      this.values.append(placeholder)
     }
+
     const hasValue = selected.length > 0
-    this.input.classList.toggle("hidden", !this.multiple && hasValue && !this.opened)
-    this.input.placeholder = hasValue ? "" : this.options.placeholder
+    this.values.classList.toggle("hidden", !this.multiple && this.opened)
+    this.searchIcon.classList.toggle("hidden", !this.searchable || (!this.multiple && !this.opened))
+    if (this.input) {
+      toggleClasses(this.input, this.classes.inputClosed, !this.multiple && !this.opened)
+      this.input.placeholder = this.multiple && !hasValue ? this.options.placeholder : this.options.searchPlaceholder
+    }
     this.clearButton.classList.toggle("hidden", !this.options.clearable || !hasValue || this.select.disabled)
+    this.syncAria()
   }
 
   makeTag(item) {
@@ -209,6 +359,7 @@ export class TamSelect {
     const remove = document.createElement("button")
     remove.type = "button"
     remove.className = this.classes.tagRemove
+    remove.disabled = this.select.disabled
     remove.setAttribute("aria-label", `Remove ${item.label}`)
     remove.innerHTML = ICONS.close
     remove.addEventListener("click", event => { event.stopPropagation(); this.deselect(item.value) })
@@ -219,60 +370,104 @@ export class TamSelect {
   renderDropdown() {
     if (!this.opened) return
     this.dropdown.replaceChildren()
+    this.dropdown.setAttribute("aria-busy", String(this.loading))
+
+    const remaining = Math.max(0, this.options.minQueryLength - this.query.trim().length)
+    if (this.options.remoteUrl && remaining > 0) {
+      const text = typeof this.options.inputTooShortText === "function" ? this.options.inputTooShortText(remaining) : this.options.inputTooShortText
+      this.renderMessage(text)
+      return this.syncActiveDescendant()
+    }
     if (this.error) {
       const error = document.createElement("div")
       error.className = this.classes.error
       error.setAttribute("role", "alert")
       error.textContent = this.error
       this.dropdown.append(error)
-      return
+      return this.syncActiveDescendant()
     }
-    if (this.loading && this.page === 1) return this.renderMessage(this.options.loadingText, true)
-
-    const visible = this.multiple ? this.filtered : this.filtered.filter(item => !item.selected)
-    visible.forEach((item, index) => this.dropdown.append(this.makeOption(item, index)))
-    if (this.options.creatable && this.query.trim() && !this.items.some(item => normalize(item.label) === normalize(this.query))) {
-      this.dropdown.append(this.makeCreateOption())
+    if (this.loading && this.loadingPage === 1) {
+      this.renderMessage(this.options.loadingText, true)
+      return this.syncActiveDescendant()
     }
-    if (!this.dropdown.children.length) this.renderMessage(this.options.noResultsText)
-    if (this.loading && this.page > 1) this.renderMessage(this.options.loadingText, true)
+
+    this.visibleItems.forEach((entry, index) => this.dropdown.append(this.makeOption(entry, index)))
+    if (!this.visibleItems.length) this.renderMessage(this.options.noResultsText)
+    if (this.loading && this.loadingPage > 1) this.renderMessage(this.options.loadingText, true)
     else if (this.hasMore) this.renderMessage(this.options.loadMoreText)
+    this.syncActiveDescendant()
   }
 
-  makeOption(item, index) {
+  makeOption(entry, index) {
     const option = document.createElement("div")
-    option.id = `${this.listboxId}-option-${index}`
-    option.dataset.value = item.value
-    option.className = [this.classes.option, index === this.activeIndex && this.classes.optionActive, item.selected && this.classes.optionSelected, item.disabled && this.classes.optionDisabled].filter(Boolean).join(" ")
+    option.id = entry.id
+    option.dataset.tamSelectEntry = String(index)
+    option.className = [
+      this.classes.option,
+      index === this.activeIndex && this.classes.optionActive,
+      index !== this.activeIndex && entry.type === "item" && entry.item.selected && this.classes.optionSelected,
+      entry.disabled && this.classes.optionDisabled
+    ].filter(Boolean).join(" ")
     option.setAttribute("role", "option")
-    option.setAttribute("aria-selected", String(Boolean(item.selected)))
-    option.setAttribute("aria-disabled", String(Boolean(item.disabled)))
-    const label = document.createElement("span")
-    label.className = "min-w-0 flex-1 truncate"
-    label.textContent = item.label
-    option.append(label)
-    if (item.selected) {
-      const check = document.createElement("span")
-      check.innerHTML = ICONS.check
-      option.append(check)
+    option.setAttribute("aria-selected", String(Boolean(entry.type === "item" && entry.item.selected)))
+    option.setAttribute("aria-disabled", String(Boolean(entry.disabled)))
+
+    if (entry.type === "create") {
+      option.textContent = typeof this.options.createText === "function" ? this.options.createText(entry.label) : this.options.createText
+    } else {
+      const item = entry.item
+      option.dataset.value = item.value
+      option.append(this.makeItemContent(item))
+      if (item.meta) {
+        const meta = document.createElement("span")
+        meta.className = this.classes.optionMeta
+        meta.textContent = item.meta
+        option.append(meta)
+      }
+      if (item.selected) {
+        const check = document.createElement("span")
+        check.innerHTML = ICONS.check
+        option.append(check)
+      }
     }
-    option.addEventListener("pointermove", () => { this.activeIndex = index; this.updateActiveOption() })
-    option.addEventListener("click", () => { if (!item.disabled) this.toggleItem(item) })
+
+    option.addEventListener("pointermove", () => { if (!entry.disabled) { this.activeIndex = index; this.updateActiveOption() } })
+    option.addEventListener("click", () => this.activateEntry(entry))
     return option
   }
 
-  makeCreateOption() {
-    const option = document.createElement("div")
-    option.className = this.classes.option
-    option.setAttribute("role", "option")
-    option.textContent = typeof this.options.createText === "function" ? this.options.createText(this.query.trim()) : this.options.createText
-    option.addEventListener("click", () => this.createItem(this.query.trim()))
-    return option
+  makeItemContent(item, selected = false) {
+    const content = document.createElement("span")
+    content.className = this.classes.optionContent
+    if (selected) content.classList.add("min-w-0", "flex-1")
+    if (item.image) {
+      const image = document.createElement("img")
+      image.className = this.classes.optionImage
+      image.src = item.image
+      image.alt = ""
+      image.loading = "lazy"
+      content.append(image)
+    }
+    const text = document.createElement("span")
+    text.className = this.classes.optionText
+    const label = document.createElement("span")
+    label.className = `${this.classes.optionLabel} truncate`
+    label.textContent = item.label
+    text.append(label)
+    if (item.detail) {
+      const detail = document.createElement("span")
+      detail.className = `${this.classes.optionDetail} truncate`
+      detail.textContent = item.detail
+      text.append(detail)
+    }
+    content.append(text)
+    return content
   }
 
   renderMessage(text, spinner = false) {
     const message = document.createElement("div")
     message.className = this.classes.message
+    message.setAttribute("role", "status")
     if (spinner) {
       const row = document.createElement("span")
       row.className = "inline-flex items-center gap-2"
@@ -280,61 +475,101 @@ export class TamSelect {
       icon.className = this.classes.spinner
       row.append(icon, document.createTextNode(text))
       message.append(row)
-    } else message.textContent = text
+    } else {
+      message.textContent = text
+    }
     this.dropdown.append(message)
   }
 
   handleKeydown(event) {
-    if (this.select.disabled) return
+    if (this.select.disabled || event.target.closest("button") && event.target !== this.trigger) return
+
     if (["ArrowDown", "ArrowUp"].includes(event.key)) {
       event.preventDefault()
+      const wasOpen = this.opened
       this.open()
-      const direction = event.key === "ArrowDown" ? 1 : -1
-      this.moveActive(direction)
+      if (wasOpen || event.key === "ArrowUp") this.moveActive(event.key === "ArrowDown" ? 1 : -1)
+      else this.updateActiveOption()
     } else if (event.key === "Enter") {
+      event.preventDefault()
       if (!this.opened) return this.open()
+      this.activateEntry(this.visibleItems[this.activeIndex])
+    } else if (event.key === " " && this.trigger) {
       event.preventDefault()
-      const item = this.filtered[this.activeIndex]
-      if (item && !item.disabled) this.toggleItem(item)
-      else if (this.options.creatable && this.query.trim()) this.createItem(this.query.trim())
-    } else if (event.key === "Escape") {
-      event.preventDefault(); this.close(); this.control.focus()
-    } else if (event.key === "Backspace" && this.multiple && !this.input.value) {
+      this.open()
+    } else if (event.key === "Escape" && this.opened) {
+      event.preventDefault()
+      this.close()
+      this.focusTarget.focus()
+    } else if (event.key === "Backspace" && this.multiple && this.input && !this.input.value) {
       const last = this.selectedItems().at(-1)
       if (last) this.deselect(last.value)
-    } else if (event.key === "Tab") this.close()
+    } else if (event.key === "Tab") {
+      this.close()
+    } else if (this.input && !this.opened && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+      this.open(false)
+    }
   }
 
   moveActive(direction) {
-    if (!this.filtered.length) return
+    if (!this.visibleItems.length) return
     let next = this.activeIndex
-    for (let count = 0; count < this.filtered.length; count += 1) {
-      next = (next + direction + this.filtered.length) % this.filtered.length
-      if (!this.filtered[next].disabled) break
+    for (let count = 0; count < this.visibleItems.length; count += 1) {
+      next = (next + direction + this.visibleItems.length) % this.visibleItems.length
+      if (!this.visibleItems[next].disabled) {
+        this.activeIndex = next
+        return this.updateActiveOption()
+      }
     }
-    this.activeIndex = next
-    this.updateActiveOption()
   }
 
   updateActiveOption() {
-    this.dropdown.querySelectorAll('[role="option"]').forEach((option, index) => toggleClasses(option, this.classes.optionActive, index === this.activeIndex))
-    const active = this.dropdown.querySelector(`#${CSS.escape(`${this.listboxId}-option-${this.activeIndex}`)}`)
-    if (active) { this.input.setAttribute("aria-activedescendant", active.id); active.scrollIntoView({ block: "nearest" }) }
+    this.dropdown.querySelectorAll("[data-tam-select-entry]").forEach(option => {
+      const index = Number(option.dataset.tamSelectEntry)
+      toggleClasses(option, this.classes.optionActive, index === this.activeIndex)
+    })
+    this.syncActiveDescendant(true)
+  }
+
+  syncActiveDescendant(scroll = false) {
+    const entry = this.visibleItems[this.activeIndex]
+    const active = entry && this.dropdown.querySelector(`[data-tam-select-entry="${this.activeIndex}"]`)
+    if (this.opened && active && !entry.disabled) {
+      this.focusTarget.setAttribute("aria-activedescendant", entry.id)
+      if (scroll) active.scrollIntoView({ block: "nearest" })
+    } else {
+      this.focusTarget.removeAttribute("aria-activedescendant")
+    }
+  }
+
+  activateEntry(entry) {
+    if (!entry || entry.disabled) return
+    if (entry.type === "create") this.createItem(entry.label, entry.value)
+    else this.toggleItem(entry.item)
   }
 
   toggleItem(item) {
+    if (item.disabled) return
     if (this.multiple && item.selected) this.deselect(item.value)
     else this.selectValue(item.value)
   }
 
   selectValue(value) {
     const item = this.ensureNativeOption(value)
+    if (item.disabled) return
     if (!this.multiple) Array.from(this.select.options).forEach(option => { option.selected = false })
     item.option.selected = true
     item.selected = true
     this.commit()
     if (this.options.closeAfterSelect) this.close()
-    else { this.input.value = ""; this.query = ""; this.filterLocal() }
+    else this.resetQueryAfterSelection()
+  }
+
+  resetQueryAfterSelection() {
+    if (this.input) this.input.value = ""
+    this.query = ""
+    if (this.options.remoteUrl) this.scheduleRemote()
+    else this.filterLocal()
   }
 
   deselect(value) {
@@ -351,130 +586,338 @@ export class TamSelect {
     this.commit()
   }
 
-  createItem(label) {
-    const value = typeof this.options.createValue === "function" ? this.options.createValue(label) : label
+  createItem(label, candidateValue = undefined) {
+    const value = candidateValue ?? (typeof this.options.createValue === "function" ? this.options.createValue(label) : label)
+    const existing = this.items.find(item => normalize(item.value) === normalize(value) || normalize(item.label) === normalize(label))
+    if (existing) {
+      this.selectValue(existing.value)
+      return existing
+    }
     const item = this.addItem({ value, label, selected: false, created: true })
     this.selectValue(item.value)
     this.emit("tam-select:create", { item })
+    return item
   }
 
   addItem(raw) {
-    const value = String(raw.value ?? raw[this.options.valueField])
+    const rawValue = raw.value ?? raw[this.options.valueField]
+    const value = String(rawValue ?? "")
     const existing = this.items.find(item => String(item.value) === value)
-    if (existing) return existing
     const label = String(raw.label ?? raw[this.options.labelField] ?? value)
+    const image = raw.image ?? raw[this.options.imageField]
+    if (existing) {
+      existing.value = value
+      existing.label = label
+      existing.detail = hasOwn(raw, "detail") ? raw.detail : existing.detail
+      existing.meta = hasOwn(raw, "meta") ? raw.meta : existing.meta
+      existing.image = image ?? existing.image
+      if (hasOwn(raw, "disabled")) existing.disabled = Boolean(raw.disabled)
+      this.syncNativeOption(existing)
+      return existing
+    }
+
     const option = new Option(label, value, Boolean(raw.selected), Boolean(raw.selected))
     option.dataset.tamSelectGenerated = ""
     this.select.add(option)
-    const item = { ...raw, value, label, option, selected: option.selected, disabled: Boolean(raw.disabled) }
-    option.disabled = item.disabled
+    const item = {
+      ...raw,
+      id: this.optionId(option),
+      value,
+      label,
+      detail: raw.detail ?? null,
+      meta: raw.meta ?? null,
+      image: image == null ? null : String(image),
+      option,
+      selected: option.selected,
+      disabled: Boolean(raw.disabled)
+    }
+    this.syncNativeOption(item)
     this.items.push(item)
-    this.filterLocal(false)
     return item
   }
 
+  upsertRemoteItem(raw) {
+    const value = String(raw?.[this.options.valueField] ?? raw?.value ?? "")
+    const label = String(raw?.[this.options.labelField] ?? raw?.label ?? value)
+    const image = raw?.[this.options.imageField] ?? raw?.image ?? null
+    const item = this.addItem({
+      value,
+      label,
+      detail: raw?.detail ?? null,
+      meta: raw?.meta ?? null,
+      image,
+      disabled: Boolean(raw?.disabled)
+    })
+    item.detail = raw?.detail ?? null
+    item.meta = raw?.meta ?? null
+    item.image = image == null ? null : String(image)
+    item.disabled = Boolean(raw?.disabled)
+    this.syncNativeOption(item)
+    return item
+  }
+
+  syncNativeOption(item) {
+    if (!item.option) return
+    item.option.value = item.value
+    item.option.textContent = item.label
+    item.option.disabled = Boolean(item.disabled)
+    this.setDataAttribute(item.option, "detail", item.detail)
+    this.setDataAttribute(item.option, "meta", item.meta)
+    this.setDataAttribute(item.option, "image", item.image)
+  }
+
+  setDataAttribute(option, name, value) {
+    if (value == null || value === "") delete option.dataset[name]
+    else option.dataset[name] = String(value)
+  }
+
+  optionId(option) {
+    if (!this.optionIds.has(option)) {
+      this.optionIdSequence += 1
+      this.optionIds.set(option, `${this.listboxId}-option-${this.optionIdSequence}`)
+    }
+    return this.optionIds.get(option)
+  }
+
   ensureNativeOption(value) {
     return this.items.find(item => String(item.value) === String(value)) || this.addItem({ value, label: value })
   }
 
   commit() {
+    if (this.select.checkValidity()) this.invalidFromEvent = false
+    this.readNativeOptions()
     this.renderSelection()
     this.renderDropdown()
+    this.syncAria()
     this.select.dispatchEvent(new Event("change", { bubbles: true }))
     this.emit("tam-select:change", { value: this.value, items: this.selectedItems() })
   }
 
-  get value() { return this.multiple ? this.selectedItems().map(item => item.value) : this.selectedItems()[0]?.value ?? "" }
+  get value() {
+    return this.multiple ? this.selectedItems().map(item => item.value) : this.selectedItems()[0]?.value ?? ""
+  }
 
   setValue(value) {
-    const values = new Set((Array.isArray(value) ? value : [value]).map(String))
-    this.items.forEach(item => { item.selected = values.has(String(item.value)); if (item.option) item.option.selected = item.selected })
+    const rawValues = value == null ? [] : (Array.isArray(value) ? value : [value])
+    const values = new Set(rawValues.map(String))
+    this.items.forEach(item => {
+      item.selected = values.has(String(item.value))
+      if (item.option) item.option.selected = item.selected
+    })
     this.commit()
   }
 
-  open() {
+  open(loadRemote = true) {
     if (this.opened || this.select.disabled) return
     this.opened = true
     this.dropdown.classList.remove("hidden")
-    this.control.setAttribute("aria-expanded", "true")
-    this.chevron.classList.add(...this.classes.chevronOpen.split(" "))
+    this.focusTarget.setAttribute("aria-expanded", "true")
+    toggleClasses(this.control, this.classes.controlOpen, true)
+    toggleClasses(this.chevron, this.classes.chevronOpen, true)
     this.renderSelection()
-    if (this.options.remoteUrl && !this.filtered.length) this.loadRemote(1)
+    if (this.options.remoteUrl && loadRemote) this.startRemoteSearch(false)
     else this.renderDropdown()
+    this.focusTarget.focus({ preventScroll: true })
     this.emit("tam-select:open")
   }
 
   close() {
     if (!this.opened) return
     this.opened = false
+    this.cancelRemoteWork()
     this.dropdown.classList.add("hidden")
-    this.control.setAttribute("aria-expanded", "false")
-    this.input.removeAttribute("aria-activedescendant")
-    this.chevron.classList.remove(...this.classes.chevronOpen.split(" "))
-    this.input.value = ""
+    this.focusTarget.setAttribute("aria-expanded", "false")
+    toggleClasses(this.control, this.classes.controlOpen, false)
+    this.focusTarget.removeAttribute("aria-activedescendant")
+    toggleClasses(this.chevron, this.classes.chevronOpen, false)
+    if (this.input) this.input.value = ""
     this.query = ""
-    this.filterLocal(false)
+    this.loading = false
+    this.loadingPage = null
+    this.error = null
+    this.hasMore = false
+    this.nextPage = null
+    if (this.options.remoteUrl) {
+      this.remoteResults = []
+      this.updateVisibleItems([])
+    } else {
+      this.filterLocal(false)
+    }
     this.renderSelection()
     this.emit("tam-select:close")
   }
 
   scheduleRemote() {
+    this.startRemoteSearch(true)
+  }
+
+  startRemoteSearch(debounced) {
     clearTimeout(this.remoteTimer)
-    if (this.query.length < this.options.minQueryLength) { this.filtered = []; return this.renderDropdown() }
-    this.remoteTimer = setTimeout(() => this.loadRemote(1), this.options.debounce)
+    this.cancelActiveRequest()
+    this.loading = false
+    this.loadingPage = null
+    this.error = null
+    this.page = 0
+    this.nextPage = null
+    this.hasMore = false
+    this.remoteResults = []
+    this.updateVisibleItems([])
+
+    if (this.query.trim().length < this.options.minQueryLength) return this.renderDropdown()
+    if (!debounced || this.options.debounce <= 0) return this.loadRemote(1, false)
+
+    this.loading = true
+    this.loadingPage = 1
+    this.renderDropdown()
+    this.remoteTimer = setTimeout(() => {
+      this.remoteTimer = null
+      this.loadRemote(1, false)
+    }, this.options.debounce)
+  }
+
+  cancelActiveRequest() {
+    if (!this.activeRequest) return
+    this.activeRequest.controller.abort()
+    this.activeRequest = null
+  }
+
+  cancelRemoteWork() {
+    clearTimeout(this.remoteTimer)
+    this.remoteTimer = null
+    this.cancelActiveRequest()
   }
 
   async loadRemote(page = 1, append = false) {
-    if (!append) this.abortController?.abort()
-    this.abortController = new AbortController()
+    if (append && (this.loading || !this.hasMore || page <= this.page)) return
+    if (this.query.trim().length < this.options.minQueryLength) return
+
+    clearTimeout(this.remoteTimer)
+    this.remoteTimer = null
+    if (!append) {
+      this.cancelActiveRequest()
+      this.remoteResults = []
+      this.updateVisibleItems([])
+    }
+
+    const requestId = ++this.requestSequence
+    const controller = new AbortController()
+    const request = { id: requestId, controller, page, query: this.query }
+    this.activeRequest = request
     this.loading = true
+    this.loadingPage = page
     this.error = null
-    this.page = page
     this.renderDropdown()
+
     try {
       const url = new URL(this.options.remoteUrl, window.location.origin)
-      url.searchParams.set(this.options.queryParam, this.query)
+      url.searchParams.set(this.options.queryParam, request.query)
       url.searchParams.set(this.options.pageParam, page)
-      const response = await fetch(url, { headers: { Accept: "application/json", ...this.options.headers }, signal: this.abortController.signal })
+      const response = await fetch(url, {
+        headers: { Accept: "application/json", ...this.options.headers },
+        signal: controller.signal
+      })
       if (!response.ok) throw new Error(`Request failed (${response.status})`)
       const data = await response.json()
-      const rawItems = this.getPath(data, this.options.itemsPath) || []
-      const remoteItems = rawItems.map(raw => this.addItem({ ...raw, value: String(raw[this.options.valueField]), label: String(raw[this.options.labelField]) }))
-      const values = new Set(remoteItems.map(item => item.value))
-      this.filtered = append ? [...this.filtered, ...remoteItems.filter(item => !this.filtered.some(old => old.value === item.value))] : this.items.filter(item => values.has(String(item.value)) || item.selected)
+      if (this.activeRequest?.id !== requestId) return
+
+      const rawItems = this.getPath(data, this.options.itemsPath)
+      const responseItems = (Array.isArray(rawItems) ? rawItems : []).map(raw => this.upsertRemoteItem(raw))
+      const combinedItems = append ? [...this.remoteResults, ...responseItems] : responseItems
+      this.remoteResults = this.deduplicateByValue(combinedItems)
+      this.page = page
       const pagination = this.getPath(data, this.options.paginationPath) || {}
-      this.hasMore = Boolean(pagination.next_page || pagination.has_more || (pagination.page && pagination.total_pages && pagination.page < pagination.total_pages))
-      this.activeIndex = this.filtered.findIndex(item => !item.disabled)
-      this.emit("tam-select:load", { items: remoteItems, pagination })
+      this.nextPage = pagination.next_page ?? null
+      this.hasMore = Boolean(this.nextPage || pagination.has_more || (pagination.page && pagination.total_pages && pagination.page < pagination.total_pages))
+      this.updateVisibleItems(this.remoteResults)
+      this.emit("tam-select:load", { items: this.deduplicateByValue(responseItems), pagination })
     } catch (error) {
-      if (error.name !== "AbortError") { this.error = error.message || "Unable to load options"; this.emit("tam-select:error", { error }) }
+      if (this.activeRequest?.id !== requestId) return
+      if (error.name !== "AbortError") {
+        this.error = error.message || "Unable to load options"
+        this.emit("tam-select:error", { error })
+      }
     } finally {
-      this.loading = false
-      this.renderDropdown()
+      if (this.activeRequest?.id === requestId) {
+        this.activeRequest = null
+        this.loading = false
+        this.loadingPage = null
+        this.renderDropdown()
+      }
     }
   }
 
-  getPath(object, path) { return String(path).split(".").reduce((value, key) => value?.[key], object) }
+  deduplicateByValue(items) {
+    const seen = new Set()
+    return items.filter(item => {
+      const value = String(item.value)
+      if (seen.has(value)) return false
+      seen.add(value)
+      return true
+    })
+  }
+
+  getPath(object, path) {
+    return String(path).split(".").reduce((value, key) => value?.[key], object)
+  }
+
+  syncAria() {
+    const labelledBy = this.labelledBy()
+    if (labelledBy) {
+      const valueReference = this.trigger ? ` ${this.valuesId}` : ""
+      this.focusTarget.setAttribute("aria-labelledby", `${labelledBy}${valueReference}`)
+      this.focusTarget.removeAttribute("aria-label")
+    } else {
+      const ariaLabel = this.select.getAttribute("aria-label") || this.options.placeholder
+      this.focusTarget.setAttribute("aria-label", ariaLabel)
+      if (this.trigger) this.focusTarget.setAttribute("aria-labelledby", this.valuesId)
+      else this.focusTarget.removeAttribute("aria-labelledby")
+    }
+
+    const describedBy = this.select.getAttribute("aria-describedby")
+    if (describedBy) this.focusTarget.setAttribute("aria-describedby", describedBy)
+    else this.focusTarget.removeAttribute("aria-describedby")
+
+    this.focusTarget.setAttribute("aria-required", String(Boolean(this.select.required)))
+    this.focusTarget.setAttribute("aria-disabled", String(Boolean(this.select.disabled)))
+    const nativeInvalid = this.select.getAttribute("aria-invalid")
+    const invalid = this.invalidFromEvent || nativeInvalid === "true"
+    if (this.invalidFromEvent) this.focusTarget.setAttribute("aria-invalid", "true")
+    else if (nativeInvalid != null) this.focusTarget.setAttribute("aria-invalid", nativeInvalid)
+    else this.focusTarget.removeAttribute("aria-invalid")
+    toggleClasses(this.control, this.classes.controlInvalid, invalid)
+  }
 
   applyDisabled() {
     toggleClasses(this.control, this.classes.controlDisabled, this.select.disabled)
-    this.control.tabIndex = this.select.disabled ? -1 : 0
-    this.input.disabled = this.select.disabled
+    this.focusTarget.disabled = this.select.disabled
+    this.clearButton.disabled = this.select.disabled
+    this.syncAria()
   }
 
-  refresh() { this.readNativeOptions(); this.applyDisabled(); this.renderSelection(); this.renderDropdown() }
+  refresh() {
+    this.readNativeOptions()
+    this.applyDisabled()
+    this.renderSelection()
+    this.renderDropdown()
+  }
 
-  emit(name, detail = {}) { this.select.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: { tamSelect: this, ...detail } })) }
+  emit(name, detail = {}) {
+    this.select.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: { tamSelect: this, ...detail } }))
+  }
 
   destroy() {
-    clearTimeout(this.remoteTimer)
-    this.abortController?.abort()
+    this.cancelRemoteWork()
     document.removeEventListener("pointerdown", this.onOutside)
     this.select.removeEventListener("change", this.onNativeChange)
+    this.select.removeEventListener("invalid", this.onNativeInvalid)
+    this.labelElements.forEach(label => label.removeEventListener("click", this.onLabelClick))
     this.wrapper.remove()
-    this.select.classList.remove("sr-only")
+    if (!this.hadSrOnlyClass) this.select.classList.remove("sr-only")
     if (this.originalTabIndex === null) this.select.removeAttribute("tabindex")
     else this.select.setAttribute("tabindex", this.originalTabIndex)
+    if (this.originalAriaHidden === null) this.select.removeAttribute("aria-hidden")
+    else this.select.setAttribute("aria-hidden", this.originalAriaHidden)
+    if (this.originalId === null) this.select.removeAttribute("id")
     TamSelect.instances.delete(this.select)
   }
 }