hotwire_combobox 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 115007b81c7f19287376a49f41aa34c43e2fb331a18459b9f47877bf282d15cf
-  data.tar.gz: b5eb9f21bd0f46f39a434ef8dea3d82a639e00b0dfb7f131c8264c77a55ac2ae
+  metadata.gz: f21dd202e0a59116a7d505c6b79df8ba287db06dfa66fd6c9159cbaad15f119d
+  data.tar.gz: 9eb4d23df658d14948200e88ee39f9dad471a61782cde5f4132767a6c81763e1
 SHA512:
-  metadata.gz: fd39e53b94270d271b0b397d4e983346ea3b99a8054d0f2ab59756a38e440b23d7bf53d63cd34e1422530aaa1fa2fe0fec57aa5d0f693778d52f0f3a2e722b18
-  data.tar.gz: b8ef213bc60a3b722d25bf4532e562151b4c660ebac0c5c75283cb045532787ff51bcb12ecafdeac28af54dc20262646d4953d5a7f306bdd43950442160831bc
+  metadata.gz: 4013316a7bcbaf7080f25987c32f0f2dc4b2a38f11e8cfb62292155d626ab2bbc7d46f5116125b351eacabeb40856e50fb03335f69c95c7e09a919a0a0ed26ca
+  data.tar.gz: 6ca62cf9479f2d6951823affeb07320e572ff02dbb34681cf3ef33dabb579103410f7ad6123ee02cd21252c2cdcbb0e06c2efb564913c52b289beaae57e1fb36

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2023 Jose Farias
+Copyright 2024 Jose Farias
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -59,9 +59,6 @@ The `options` argument takes an array of any objects which respond to:
 | autocompletable_as | Used to autocomplete the input element when the user types into it. Falls back to calling `display` on the object if not provided.         |
 | display            | Used as a short-hand for other attributes. See the rest of the list for details.                                                           |
 
-> [!NOTE]
-> The `id` attribute is required only if `value` is not provided.
-
 You can use the `combobox_options` helper to create an array of option objects which respond to the above methods:
 
 ```ruby
@@ -89,7 +86,7 @@ Additionally, you can pass the following [Stimulus class values](https://stimulu
 
 ### Validity
 
-The hidden input can't have a value that's not in the list of options.
+Unless `name_when_new` is passed, the hidden input can't have a value that's not in the list of options.
 
 If a nonexistent value is typed into the combobox, the value of the hidden input will be set empty.
 

data/app/assets/javascripts/controllers/hw_combobox_controller.js

@@ -1,225 +1,69 @@
+import Combobox from "models/combobox"
+import { Concerns } from "helpers"
 import { Controller } from "@hotwired/stimulus"
 
-export default class extends Controller {
-  static classes = [ "selected", "invalid" ]
-  static targets = [ "combobox", "listbox", "valueField" ]
-  static values = { expanded: Boolean, filterableAttribute: String, autocompletableAttribute: String }
-
-  connect() {
-    if (this.valueFieldTarget.value) {
-      this.selectOptionByValue(this.valueFieldTarget.value)
-    }
-  }
-
-  open() {
-    this.expandedValue = true
-  }
-
-  close() {
-    if (!this.isOpen) return
-    this.commitSelection()
-    this.expandedValue = false
-  }
-
-  selectOption(event) {
-    this.select(event.currentTarget)
-    this.close()
-  }
-
-  filter(event) {
-    const query = this.comboboxTarget.value.trim()
-
-    this.open()
-
-    this.allOptionElements.forEach(applyFilter(query, { matching: this.filterableAttributeValue }))
-
-    if (event.inputType === "deleteContentBackward") {
-      this.deselect(this.selectedOptionElement)
-    } else {
-      this.select(this.visibleOptionElements[0])
-    }
-  }
-
-  navigate(event) {
-    this.keyHandlers[event.key]?.call(this, event)
-  }
-
-  closeOnClickOutside({ target }) {
-    if (this.element.contains(target)) return
-
-    this.close()
+const concerns = [
+  Controller,
+  Combobox.Actors,
+  Combobox.AsyncLoading,
+  Combobox.Autocomplete,
+  Combobox.Dialog,
+  Combobox.Filtering,
+  Combobox.Navigation,
+  Combobox.Options,
+  Combobox.Selection,
+  Combobox.Toggle,
+  Combobox.Validity
+]
+
+export default class HwComboboxController extends Concerns(...concerns) {
+  static classes = [
+    "invalid",
+    "selected"
+  ]
+
+  static targets = [
+    "combobox",
+    "dialog",
+    "dialogCombobox",
+    "dialogFocusTrap",
+    "dialogListbox",
+    "handle",
+    "hiddenField",
+    "listbox"
+  ]
+
+  static values = {
+    asyncSrc: String,
+    autocompletableAttribute: String,
+    autocomplete: String,
+    expanded: Boolean,
+    filterableAttribute: String,
+    nameWhenNew: String,
+    originalName: String,
+    smallViewportMaxWidth: String
+  }
+
+  initialize() {
+    this._initializeActors()
+    this._initializeFiltering()
   }
 
-  closeOnFocusOutside({ target }) {
-    if (!this.isOpen) return
-    if (this.element.contains(target)) return
-    if (target.matches("main")) return
-
-    this.close()
-  }
-
-  // private
-
-  keyHandlers = {
-    ArrowUp(event) {
-      this.selectIndex(this.selectedOptionIndex - 1)
-      cancel(event)
-    },
-    ArrowDown(event) {
-      this.selectIndex(this.selectedOptionIndex + 1)
-      cancel(event)
-    },
-    Home(event) {
-      this.selectIndex(0)
-      cancel(event)
-    },
-    End(event) {
-      this.selectIndex(this.visibleOptionElements.length - 1)
-      cancel(event)
-    },
-    Enter(event) {
-      this.close()
-      cancel(event)
-    }
+  connect() {
+    this._connectSelection()
+    this._connectListAutocomplete()
+    this._connectDialog()
   }
 
-  commitSelection() {
-    this.select(this.selectedOptionElement, { force: true })
+  disconnect() {
+    this._disconnectDialog()
   }
 
   expandedValueChanged() {
     if (this.expandedValue) {
-      this.expand()
-    } else {
-      this.collapse()
-    }
-  }
-
-  expand() {
-    this.listboxTarget.hidden = false
-    this.comboboxTarget.setAttribute("aria-expanded", true)
-  }
-
-  collapse() {
-    this.listboxTarget.hidden = true
-    this.comboboxTarget.setAttribute("aria-expanded", false)
-  }
-
-  select(option, { force = false } = {}) {
-    this.allOptionElements.forEach(option => this.deselect(option))
-
-    if (option) {
-      if (this.hasSelectedClass) option.classList.add(this.selectedClass)
-      if (this.hasInvalidClass) this.comboboxTarget.classList.remove(this.invalidClass)
-
-      this.maybeAutocompleteWith(option, { force })
-      this.executeSelect(option, { selected: true })
-    } else {
-      if (this.valueIsInvalid) {
-        if (this.hasInvalidClass) this.comboboxTarget.classList.add(this.invalidClass)
-
-        this.comboboxTarget.setAttribute("aria-invalid", true)
-        this.comboboxTarget.setAttribute("aria-errormessage", `Please select a valid option for ${this.comboboxTarget.name}`)
-      }
-    }
-  }
-
-  selectIndex(index) {
-    const option = wrapAroundAccess(this.visibleOptionElements, index)
-    this.select(option, { force: true })
-  }
-
-  selectOptionByValue(value) {
-    this.allOptions.find(option => option.dataset.value === value)?.click()
-  }
-
-  deselect(option) {
-    if (option) {
-      if (this.hasSelectedClass) option.classList.remove(this.selectedClass)
-      this.executeSelect(option, { selected: false })
-    }
-  }
-
-  executeSelect(option, { selected }) {
-    if (selected) {
-      option.setAttribute("aria-selected", true)
-      this.valueFieldTarget.value = option.dataset.value
-    } else {
-      option.setAttribute("aria-selected", false)
-      this.valueFieldTarget.value = null
-    }
-  }
-
-  maybeAutocompleteWith(option, { force }) {
-    const typedValue = this.comboboxTarget.value
-    const autocompletedValue = option.dataset.autocompletableAs
-
-    if (force) {
-      this.comboboxTarget.value = autocompletedValue
-      this.comboboxTarget.setSelectionRange(autocompletedValue.length, autocompletedValue.length)
-    } else if (autocompletedValue.toLowerCase().startsWith(typedValue.toLowerCase())) {
-      this.comboboxTarget.value = autocompletedValue
-      this.comboboxTarget.setSelectionRange(typedValue.length, autocompletedValue.length)
-    }
-  }
-
-  get allOptions() {
-    return Array.from(this.allOptionElements)
-  }
-
-  get allOptionElements() {
-    return this.listboxTarget.querySelectorAll(`[${this.filterableAttributeValue}]`)
-  }
-
-  get visibleOptionElements() {
-    return [ ...this.allOptionElements ].filter(visible)
-  }
-
-  get selectedOptionElement() {
-    return this.listboxTarget.querySelector("[role=option][aria-selected=true]")
-  }
-
-  get selectedOptionIndex() {
-    return [ ...this.visibleOptionElements ].indexOf(this.selectedOptionElement)
-  }
-
-  get isOpen() {
-    return this.expandedValue
-  }
-
-  get valueIsInvalid() {
-    const isRequiredAndEmpty = this.comboboxTarget.required && !this.valueFieldTarget.value
-    return isRequiredAndEmpty
-  }
-}
-
-function applyFilter(query, { matching }) {
-  return (target) => {
-    if (query) {
-      const value = target.getAttribute(matching) || ""
-      const match = value.toLowerCase().includes(query.toLowerCase())
-
-      target.hidden = !match
+      this._expand()
     } else {
-      target.hidden = false
+      this._collapse()
     }
   }
 }
-
-function visible(target) {
-  return !(target.hidden || target.closest("[hidden]"))
-}
-
-function wrapAroundAccess(array, index) {
-  const first = 0
-  const last = array.length - 1
-
-  if (index < first) return array[last]
-  if (index > last) return array[first]
-  return array[index]
-}
-
-function cancel(event) {
-  event.stopPropagation()
-  event.preventDefault()
-}

data/app/assets/javascripts/helpers.js

@@ -0,0 +1,52 @@
+export function Concerns(Base, ...mixins) {
+  return mixins.reduce((accumulator, current) => current(accumulator), Base)
+}
+
+export function visible(target) {
+  return !(target.hidden || target.closest("[hidden]"))
+}
+
+export function wrapAroundAccess(array, index) {
+  const first = 0
+  const last = array.length - 1
+
+  if (index < first) return array[last]
+  if (index > last) return array[first]
+  return array[index]
+}
+
+export function applyFilter(query, { matching }) {
+  return (target) => {
+    if (query) {
+      const value = target.getAttribute(matching) || ""
+      const match = value.toLowerCase().includes(query.toLowerCase())
+
+      target.hidden = !match
+    } else {
+      target.hidden = false
+    }
+  }
+}
+
+export function cancel(event) {
+  event.stopPropagation()
+  event.preventDefault()
+}
+
+export function startsWith(string, substring) {
+  return string.toLowerCase().startsWith(substring.toLowerCase())
+}
+
+export function nextFrame() {
+  return new Promise(requestAnimationFrame)
+}
+
+export function debounce(fn, delay = 150) {
+  let timeoutId = null
+
+  return (...args) => {
+    const callback = () => fn.apply(this, args)
+    clearTimeout(timeoutId)
+    timeoutId = setTimeout(callback, delay)
+  }
+}

data/app/assets/javascripts/models/combobox/actors.js

@@ -0,0 +1,24 @@
+import Combobox from "models/combobox/base"
+
+Combobox.Actors = Base => class extends Base {
+  _initializeActors() {
+    this._actingListbox = this.listboxTarget
+    this._actingCombobox = this.comboboxTarget
+  }
+
+  get _actingListbox() {
+    return this.actingListbox
+  }
+
+  set _actingListbox(listbox) {
+    this.actingListbox = listbox
+  }
+
+  get _actingCombobox() {
+    return this.actingCombobox
+  }
+
+  set _actingCombobox(combobox) {
+    this.actingCombobox = combobox
+  }
+}

data/app/assets/javascripts/models/combobox/async_loading.js

@@ -0,0 +1,7 @@
+import Combobox from "models/combobox/base"
+
+Combobox.AsyncLoading = Base => class extends Base {
+  get _isAsync() {
+    return this.hasAsyncSrcValue
+  }
+}

data/app/assets/javascripts/models/combobox/autocomplete.js

@@ -0,0 +1,39 @@
+import Combobox from "models/combobox/base"
+import { startsWith } from "helpers"
+
+Combobox.Autocomplete = Base => class extends Base {
+  _connectListAutocomplete() {
+    if (!this._autocompletesList) {
+      this._visuallyHideListbox()
+    }
+  }
+
+  _maybeAutocompleteWith(option, { force }) {
+    if (!this._autocompletesInline && !force) return
+
+    const typedValue = this._actingCombobox.value
+    const autocompletedValue = option.getAttribute(this.autocompletableAttributeValue)
+
+    if (force) {
+      this._actingCombobox.value = autocompletedValue
+      this._actingCombobox.setSelectionRange(autocompletedValue.length, autocompletedValue.length)
+    } else if (startsWith(autocompletedValue, typedValue)) {
+      this._actingCombobox.value = autocompletedValue
+      this._actingCombobox.setSelectionRange(typedValue.length, autocompletedValue.length)
+    }
+  }
+
+  // +visuallyHideListbox+ hides the listbox from the user,
+  // but makes it still searchable by JS.
+  _visuallyHideListbox() {
+    this.listboxTarget.style.display = "none"
+  }
+
+  get _autocompletesList() {
+    return this.autocompleteValue === "both" || this.autocompleteValue === "list"
+  }
+
+  get _autocompletesInline() {
+    return this.autocompleteValue === "both" || this.autocompleteValue === "inline"
+  }
+}

data/app/assets/javascripts/models/combobox/base.js

@@ -0,0 +1,3 @@
+const Combobox = {}
+
+export default Combobox

data/app/assets/javascripts/models/combobox/dialog.js

@@ -0,0 +1,50 @@
+import Combobox from "models/combobox/base"
+
+Combobox.Dialog = Base => class extends Base {
+  _connectDialog() {
+    if (window.visualViewport) {
+      window.visualViewport.addEventListener("resize", this._resizeDialog)
+    }
+  }
+
+  _disconnectDialog() {
+    if (window.visualViewport) {
+      window.visualViewport.removeEventListener("resize", this._resizeDialog)
+    }
+  }
+
+  _moveArtifactsToDialog() {
+    this.dialogComboboxTarget.value = this.actingCombobox.value
+
+    this._actingCombobox = this.dialogComboboxTarget
+    this._actingListbox = this.dialogListboxTarget
+
+    this.dialogListboxTarget.append(...this.listboxTarget.children)
+  }
+
+  _moveArtifactsInline() {
+    this.comboboxTarget.value = this.actingCombobox.value
+
+    this._actingCombobox = this.comboboxTarget
+    this._actingListbox = this.listboxTarget
+
+    this.listboxTarget.append(...this.dialogListboxTarget.children)
+  }
+
+  _resizeDialog = () => {
+    const fullHeight = window.innerHeight
+    const viewportHeight = window.visualViewport.height
+    this.dialogTarget.style.setProperty("--hw-dialog-bottom-padding", `${fullHeight - viewportHeight}px`)
+  }
+
+  // After closing a dialog, focus returns to the last focused element.
+  // +preventFocusingComboboxAfterClosingDialog+ focuses a placeholder element before opening
+  // the dialog, so that the combobox is not focused again after closing, which would reopen.
+  _preventFocusingComboboxAfterClosingDialog() {
+    this.dialogFocusTrapTarget.focus()
+  }
+
+  get _smallViewport() {
+    return window.matchMedia(`(max-width: ${this.smallViewportMaxWidthValue})`).matches
+  }
+}

data/app/assets/javascripts/models/combobox/filtering.js

@@ -0,0 +1,57 @@
+
+import Combobox from "models/combobox/base"
+import { applyFilter, nextFrame, debounce } from "helpers"
+import { get } from "@rails/request.js"
+
+Combobox.Filtering = Base => class extends Base {
+  filter(event) {
+    if (this._isAsync) {
+      this._debouncedFilterAsync(event)
+    } else {
+      this._filterSync(event)
+    }
+  }
+
+  _initializeFiltering() {
+    this._debouncedFilterAsync = debounce(this._debouncedFilterAsync.bind(this))
+  }
+
+  _debouncedFilterAsync(event) {
+    this._filterAsync(event)
+  }
+
+  async _filterAsync(event) {
+    const q = this._actingCombobox.value.trim()
+
+    await get(this.asyncSrcValue, { responseKind: "turbo-stream", query: { q } })
+
+    this._afterTurboStreamRender(() => this._commitFilter(q, event))
+  }
+
+  _filterSync(event) {
+    const query = this._actingCombobox.value.trim()
+
+    this.open()
+
+    this._allOptionElements.forEach(applyFilter(query, { matching: this.filterableAttributeValue }))
+
+    this._commitFilter(query, event)
+  }
+
+  _commitFilter(query, event) {
+    const isDeleting = event.inputType === "deleteContentBackward"
+
+    if (this._isValidNewOption(query, { ignoreAutocomplete: isDeleting })) {
+      this._selectNew(query)
+    } else if (isDeleting) {
+      this._deselect()
+    } else {
+      this._select(this._visibleOptionElements[0])
+    }
+  }
+
+  async _afterTurboStreamRender(callback) {
+    await nextFrame()
+    callback()
+  }
+}

data/app/assets/javascripts/models/combobox/navigation.js

@@ -0,0 +1,39 @@
+import Combobox from "models/combobox/base"
+import { cancel } from "helpers"
+
+Combobox.Navigation = Base => class extends Base {
+  navigate(event) {
+    if (this._autocompletesList) {
+      this._keyHandlers[event.key]?.call(this, event)
+    }
+  }
+
+  _keyHandlers = {
+    ArrowUp: (event) => {
+      this._selectIndex(this._selectedOptionIndex - 1)
+      cancel(event)
+    },
+    ArrowDown: (event) => {
+      this._selectIndex(this._selectedOptionIndex + 1)
+      cancel(event)
+    },
+    Home: (event) => {
+      this._selectIndex(0)
+      cancel(event)
+    },
+    End: (event) => {
+      this._selectIndex(this._visibleOptionElements.length - 1)
+      cancel(event)
+    },
+    Enter: (event) => {
+      this.close()
+      this._actingCombobox.blur()
+      cancel(event)
+    },
+    Escape: (event) => {
+      this.close()
+      this._actingCombobox.blur()
+      cancel(event)
+    }
+  }
+}

data/app/assets/javascripts/models/combobox/options.js

@@ -0,0 +1,41 @@
+import Combobox from "models/combobox/base"
+import { visible, startsWith } from "helpers"
+
+Combobox.Options = Base => class extends Base {
+  _resetOptions() {
+    this._deselect()
+    this.hiddenFieldTarget.name = this.originalNameValue
+  }
+
+  _isValidNewOption(query, { ignoreAutocomplete = false } = {}) {
+    const typedValue = this._actingCombobox.value
+    const autocompletedValue = this._visibleOptionElements[0]?.getAttribute(this.autocompletableAttributeValue)
+    const insufficentAutocomplete = !autocompletedValue || !startsWith(autocompletedValue, typedValue)
+
+    return query.length > 0 && this._allowNew && (ignoreAutocomplete || insufficentAutocomplete)
+  }
+
+  get _allowNew() {
+    return !!this.nameWhenNewValue
+  }
+
+  get _allOptions() {
+    return Array.from(this._allOptionElements)
+  }
+
+  get _allOptionElements() {
+    return this._actingListbox.querySelectorAll(`[${this.filterableAttributeValue}]`)
+  }
+
+  get _visibleOptionElements() {
+    return [ ...this._allOptionElements ].filter(visible)
+  }
+
+  get _selectedOptionElement() {
+    return this._actingListbox.querySelector("[role=option][aria-selected=true]")
+  }
+
+  get _selectedOptionIndex() {
+    return [ ...this._visibleOptionElements ].indexOf(this._selectedOptionElement)
+  }
+}