advanced_select 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 254f883547b3f323b98150becc0db7f8ff76f609a9a7186a5d1eb8903a0afb7f
-  data.tar.gz: 56b4d1866feaad22d4c4ed00bb2ab573240dbedda3d2f7cc6a1759c7da53b571
+  metadata.gz: 9be8d05d537d5e36a565546c0f821c68a6a62cd5e3978cbbe23d3ef7451c1f2a
+  data.tar.gz: c6c4c0667ef096fd55e57024621eb9a21d2338ecbef2c2305e2bf2edab0fad4d
 SHA512:
-  metadata.gz: f6a74b01aed5465044972b7f89d75148a9192120d8bba05e7a212899a11715198a3a4743092e329e1dc8ae4ccb0c86c2ab21ccafb48b88fa52059212b6d4acc3
-  data.tar.gz: 9df6c7b80f331cdc57fabaddce592f1f899728fe643d73ac3c98149acdb6b9f4c7a559e2fd87113655338ece19695fcfed7fbb6b570808bf02395f44c568301b
+  metadata.gz: 492cee1cf22c71e9c6e328052bb3ff7c49d519816c06ebe8610f2c0d07d2cbcfd9ebe09383ac3a69e696497295a34015aa467f004d46e40194ae4cc7d7538473
+  data.tar.gz: 65b3749af47dc024f475284c0998657190f5c68c27da5578d93dfd35669a4eb9c319d3b1b6df1a07fb16157eb0f8897ed4154ab7b54f5e49d8ad7dda3d1bec84

data/README.md

@@ -75,7 +75,7 @@ AdvancedSelect does not provide query objects, model concerns, authorization log
 Add the gem to the host Rails app:
 
 ```ruby
-gem "advanced_select", "~> 0.1.0"
+gem "advanced_select", "~> 0.1.4"
 ```
 
 Run the installer:
@@ -502,6 +502,48 @@ Use `dependent_fields` when a remote option endpoint depends on another field va
 
 The remote request will include `parent_id=<current field value>`.
 
+By default the field is **eager**: it listens for `change` on each dependent field and reloads its options immediately, without waiting for the dropdown to open. When a parent changes, the field clears its current value, fetches fresh options for the new parent, and (combined with auto select, below) can settle on a value while staying closed. It also loads once on initial render so a parent's default value is reflected right away. An existing server-rendered selection is left untouched.
+
+Because the field re-broadcasts a `change` event whenever its own value changes, you can chain advanced selects: a child can depend on another advanced select via its hidden input id (`dependent_fields: { parent_id: "#record_parent_id" }`).
+
+Pass `eager: false` for the lazy behaviour instead — options are only fetched when the dropdown opens, and the field does not react to parent changes until then:
+
+```erb
+<%= advanced_select_tag(
+  "record[item_id]",
+  id: "record_item_id",
+  selected: selected_option,
+  options: [],
+  placeholder: t(".item_placeholder"),
+  options_url: item_options_path,
+  dependent_fields: { parent_id: "#record_parent_id" },
+  eager: false
+) %>
+```
+
+### Auto Select Single Option
+
+When a remote option list is populated and resolves to exactly one selectable option, the field selects that option automatically. This is enabled by default and is meant for dependent fields where a parent value narrows the children down to a single valid choice.
+
+Auto selection only runs when the dropdown is **populated through a remote request** (the cascade case): it fires after the options finish loading, either when the dropdown opens or — with the default eager dependent fields above — as soon as a parent value loads them, so a single valid option is selected without the user opening the field. It does **not** run for statically rendered local options on page load, and it never triggers while the user is actively typing a search.
+
+It never overrides an existing selection and is skipped for `multiple` fields.
+
+Pass `auto_select_single: false` to opt out:
+
+```erb
+<%= advanced_select_tag(
+  "record[item_id]",
+  id: "record_item_id",
+  selected: selected_option,
+  options: [],
+  placeholder: t(".item_placeholder"),
+  options_url: item_options_path,
+  dependent_fields: { parent_id: "#record_parent_id" },
+  auto_select_single: false
+) %>
+```
+
 ### Custom Option Content
 
 Use a custom option content partial when an option needs richer content. The engine still renders the option button, Stimulus data attributes, and ARIA attributes:
@@ -631,6 +673,8 @@ advanced_select_tag(
   add_mode: false,
   dependent_fields: {},
   include_hidden: true,
+  auto_select_single: true,
+  eager: true,
   option_content_partial: nil,
   classes: {},
   append_classes: {}

data/app/javascript/advanced_select/advanced_select_controller.js

@@ -5,8 +5,10 @@ export default class extends Controller {
   static targets = ["hiddenFields", "trigger", "summary", "dropdown", "search", "options", "caret", "clear"]
   static values = {
     addMode: Boolean,
+    autoSelectSingle: { type: Boolean, default: true },
     delay: { type: Number, default: 200 },
     dependentFields: Object,
+    eager: { type: Boolean, default: true },
     emptyText: String,
     errorText: String,
     includeHidden: { type: Boolean, default: true },
@@ -41,11 +43,16 @@ export default class extends Controller {
     }))
     this.close = this.close.bind(this)
     this.renderOptionsState()
+    this.setupEagerDependentFields()
   }
 
   disconnect() {
     window.clearTimeout(this.timer)
     document.removeEventListener("click", this.close)
+
+    if (this.dependentChangeListener) {
+      document.removeEventListener("change", this.dependentChangeListener)
+    }
   }
 
   toggle(event) {
@@ -63,7 +70,7 @@ export default class extends Controller {
     this.triggerTarget.setAttribute("aria-expanded", "true")
     document.addEventListener("click", this.close)
     this.activate(-1)
-    this.fetchOptions({ selected: true })
+    this.fetchOptions({ selected: true, autoSelect: true })
 
     if (this.searchableValue) {
       requestAnimationFrame(() => this.searchTarget.focus())
@@ -186,7 +193,7 @@ export default class extends Controller {
     return (text || "").trim().toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "")
   }
 
-  fetchOptions({ selected = false } = {}) {
+  fetchOptions({ selected = false, autoSelect = false, eager = false } = {}) {
     if (!this.urlValue) {
       return
     }
@@ -221,23 +228,27 @@ export default class extends Controller {
         return response.text()
       })
       .then((html) => {
-        if (!this.expanded || requestSequence !== this.requestSequence) {
+        if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
         Turbo.renderStreamMessage(html)
         requestAnimationFrame(() => {
-          if (!this.expanded || requestSequence !== this.requestSequence) {
+          if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
             return
           }
 
           this.currentOptionsTarget.setAttribute("aria-busy", "false")
           this.renderOptionsState()
           this.activate(-1)
+
+          if (autoSelect) {
+            this.autoSelectSingle()
+          }
         })
       })
       .catch(() => {
-        if (!this.expanded || requestSequence !== this.requestSequence) {
+        if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
@@ -294,6 +305,14 @@ export default class extends Controller {
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
     this.clearTarget.classList.toggle("hidden", this.selectedValue.length === 0)
+    this.dispatchValueChange()
+  }
+
+  dispatchValueChange() {
+    const input = this.hiddenFieldsTarget.querySelector("input")
+    if (input) {
+      input.dispatchEvent(new Event("change", { bubbles: true }))
+    }
   }
 
   renderOptionsState() {
@@ -319,6 +338,54 @@ export default class extends Controller {
     }
   }
 
+  setupEagerDependentFields() {
+    if (!this.eagerValue || !this.urlValue) {
+      return
+    }
+
+    this.dependentSelectors = [...new Set(Object.values(this.dependentFieldsValue))]
+    if (this.dependentSelectors.length === 0) {
+      return
+    }
+
+    this.dependentChangeListener = (event) => {
+      if (event.target instanceof Element && this.dependentSelectors.some((selector) => event.target.matches(selector))) {
+        this.reloadDependentOptions()
+      }
+    }
+    document.addEventListener("change", this.dependentChangeListener)
+
+    if (this.selectedValue.length === 0) {
+      this.fetchOptions({ eager: true, autoSelect: true })
+    }
+  }
+
+  reloadDependentOptions() {
+    this.selectedValue = []
+    this.renderSelection()
+    this.clearSearch()
+    this.fetchOptions({ eager: true, autoSelect: true })
+  }
+
+  autoSelectSingle() {
+    if (!this.autoSelectSingleValue || this.multipleValue || this.selectedValue.length > 0) {
+      return
+    }
+
+    const options = this.selectableOptionElements
+    if (options.length !== 1) {
+      return
+    }
+
+    const option = options[0]
+    this.selectOption(
+      option.dataset.advancedSelectValueParam,
+      option.dataset.advancedSelectLabelParam,
+      option.dataset.advancedSelectSubmitValueParam || option.dataset.advancedSelectValueParam,
+      { displayLabel: option.dataset.advancedSelectDisplayLabelParam, refreshOptions: false }
+    )
+  }
+
   chooseActiveOption() {
     if (this.activeOption.hasAttribute("data-advanced-select-add-option")) {
       this.addOption(
@@ -364,6 +431,10 @@ export default class extends Controller {
     return this.optionElements[this.activeIndex]
   }
 
+  get selectableOptionElements() {
+    return Array.from(this.currentOptionsTarget.querySelectorAll("[data-advanced-select-option]")).filter((option) => !option.classList.contains("hidden"))
+  }
+
   get currentOptionsTarget() {
     return document.getElementById(this.targetIdValue) || this.optionsTarget
   }

data/app/views/advanced_select/_select.html.erb

@@ -13,6 +13,8 @@
      data-advanced-select-searchable-value="<%= searchable %>"
      data-advanced-select-add-mode-value="<%= add_mode %>"
      data-advanced-select-include-hidden-value="<%= include_hidden %>"
+     data-advanced-select-auto-select-single-value="<%= auto_select_single %>"
+     data-advanced-select-eager-value="<%= eager %>"
      data-advanced-select-placeholder-class="<%= advanced_select_class(class_map, :placeholder) %>"
      data-advanced-select-value-class="<%= advanced_select_class(class_map, :value) %>"
      data-advanced-select-token-class="<%= advanced_select_class(class_map, :token) %>"

data/lib/advanced_select/helper.rb

@@ -1,6 +1,6 @@
 module AdvancedSelect
   module Helper
-    def advanced_select_tag(name, id:, selected:, options:, placeholder:, options_url: nil, multiple: false, searchable: true, add_mode: false, dependent_fields: {}, include_hidden: true, option_content_partial: nil, classes: {}, append_classes: {})
+    def advanced_select_tag(name, id:, selected:, options:, placeholder:, options_url: nil, multiple: false, searchable: true, add_mode: false, dependent_fields: {}, include_hidden: true, auto_select_single: true, eager: true, option_content_partial: nil, classes: {}, append_classes: {})
       selected_options = advanced_select_selected_options(selected)
       class_map = advanced_select_class_map(classes, append_classes)
 
@@ -16,6 +16,8 @@ module AdvancedSelect
         add_mode: add_mode,
         dependent_fields: dependent_fields,
         include_hidden: include_hidden,
+        auto_select_single: auto_select_single,
+        eager: eager,
         target_id: "#{id}_options",
         option_content_partial: option_content_partial,
         class_map: class_map

data/lib/advanced_select/version.rb

@@ -1,3 +1,3 @@
 module AdvancedSelect
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/lib/generators/advanced_select/install/templates/advanced_select_controller.js

@@ -5,8 +5,10 @@ export default class extends Controller {
   static targets = ["hiddenFields", "trigger", "summary", "dropdown", "search", "options", "caret", "clear"]
   static values = {
     addMode: Boolean,
+    autoSelectSingle: { type: Boolean, default: true },
     delay: { type: Number, default: 200 },
     dependentFields: Object,
+    eager: { type: Boolean, default: true },
     emptyText: String,
     errorText: String,
     includeHidden: { type: Boolean, default: true },
@@ -41,11 +43,16 @@ export default class extends Controller {
     }))
     this.close = this.close.bind(this)
     this.renderOptionsState()
+    this.setupEagerDependentFields()
   }
 
   disconnect() {
     window.clearTimeout(this.timer)
     document.removeEventListener("click", this.close)
+
+    if (this.dependentChangeListener) {
+      document.removeEventListener("change", this.dependentChangeListener)
+    }
   }
 
   toggle(event) {
@@ -63,7 +70,7 @@ export default class extends Controller {
     this.triggerTarget.setAttribute("aria-expanded", "true")
     document.addEventListener("click", this.close)
     this.activate(-1)
-    this.fetchOptions({ selected: true })
+    this.fetchOptions({ selected: true, autoSelect: true })
 
     if (this.searchableValue) {
       requestAnimationFrame(() => this.searchTarget.focus())
@@ -186,7 +193,7 @@ export default class extends Controller {
     return (text || "").trim().toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "")
   }
 
-  fetchOptions({ selected = false } = {}) {
+  fetchOptions({ selected = false, autoSelect = false, eager = false } = {}) {
     if (!this.urlValue) {
       return
     }
@@ -221,23 +228,27 @@ export default class extends Controller {
         return response.text()
       })
       .then((html) => {
-        if (!this.expanded || requestSequence !== this.requestSequence) {
+        if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
         Turbo.renderStreamMessage(html)
         requestAnimationFrame(() => {
-          if (!this.expanded || requestSequence !== this.requestSequence) {
+          if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
             return
           }
 
           this.currentOptionsTarget.setAttribute("aria-busy", "false")
           this.renderOptionsState()
           this.activate(-1)
+
+          if (autoSelect) {
+            this.autoSelectSingle()
+          }
         })
       })
       .catch(() => {
-        if (!this.expanded || requestSequence !== this.requestSequence) {
+        if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
@@ -294,6 +305,14 @@ export default class extends Controller {
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
     this.clearTarget.classList.toggle("hidden", this.selectedValue.length === 0)
+    this.dispatchValueChange()
+  }
+
+  dispatchValueChange() {
+    const input = this.hiddenFieldsTarget.querySelector("input")
+    if (input) {
+      input.dispatchEvent(new Event("change", { bubbles: true }))
+    }
   }
 
   renderOptionsState() {
@@ -319,6 +338,56 @@ export default class extends Controller {
     }
   }
 
+  setupEagerDependentFields() {
+    if (!this.eagerValue || !this.urlValue) {
+      return
+    }
+
+    this.dependentSelectors = [...new Set(Object.values(this.dependentFieldsValue))]
+    if (this.dependentSelectors.length === 0) {
+      return
+    }
+
+    // Delegated on document so it keeps working after a parent advanced select
+    // rewrites its hidden input on each selection.
+    this.dependentChangeListener = (event) => {
+      if (event.target instanceof Element && this.dependentSelectors.some((selector) => event.target.matches(selector))) {
+        this.reloadDependentOptions()
+      }
+    }
+    document.addEventListener("change", this.dependentChangeListener)
+
+    if (this.selectedValue.length === 0) {
+      this.fetchOptions({ eager: true, autoSelect: true })
+    }
+  }
+
+  reloadDependentOptions() {
+    this.selectedValue = []
+    this.renderSelection()
+    this.clearSearch()
+    this.fetchOptions({ eager: true, autoSelect: true })
+  }
+
+  autoSelectSingle() {
+    if (!this.autoSelectSingleValue || this.multipleValue || this.selectedValue.length > 0) {
+      return
+    }
+
+    const options = this.selectableOptionElements
+    if (options.length !== 1) {
+      return
+    }
+
+    const option = options[0]
+    this.selectOption(
+      option.dataset.advancedSelectValueParam,
+      option.dataset.advancedSelectLabelParam,
+      option.dataset.advancedSelectSubmitValueParam || option.dataset.advancedSelectValueParam,
+      { displayLabel: option.dataset.advancedSelectDisplayLabelParam, refreshOptions: false }
+    )
+  }
+
   chooseActiveOption() {
     if (this.activeOption.hasAttribute("data-advanced-select-add-option")) {
       this.addOption(
@@ -364,6 +433,10 @@ export default class extends Controller {
     return this.optionElements[this.activeIndex]
   }
 
+  get selectableOptionElements() {
+    return Array.from(this.currentOptionsTarget.querySelectorAll("[data-advanced-select-option]")).filter((option) => !option.classList.contains("hidden"))
+  }
+
   get currentOptionsTarget() {
     return document.getElementById(this.targetIdValue) || this.optionsTarget
   }
@@ -448,4 +521,4 @@ export default class extends Controller {
   get expanded() {
     return this.triggerTarget.getAttribute("aria-expanded") === "true"
   }
-}
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: advanced_select
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Mehmet Celik