advanced_select 0.1.10 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3268b609f1b4c08af63c6bc791459345dbbdfb1afa3a1e9974569392e27b417a
-  data.tar.gz: 525a23db2449fd8867d83fb7b1647d75d6d194a4791971fec0cb55de48a2d1c8
+  metadata.gz: be334c14eaabfa7e2d3685deb4f1404b7187cb51c94d8a8dcb17b17e70bc5435
+  data.tar.gz: b9a676e2e4a64345631612285e8a362034b4efaaf60650cd201eadb2fa41b5a0
 SHA512:
-  metadata.gz: f66187ab2d1914f3de4c933fecbf3b9237684b4c8d911de1582426002f6d099820181401137d6c0896d3cdb99b1af38ecf12acbdd8dd29ff7aac6af965e2c587
-  data.tar.gz: 3a240d713742fcd791541b4272e499d6036d8ada44eb8697529628d9b1ceb9092678362bf435bcd25bc8b33d95e6f9a95d4a752e23b9b587fe814b738ddb9cd6
+  metadata.gz: be666dac14558aa5437cdf536c4bac3e8b392c61694904794a9d935de038152d6852c19e1d537a833f80836ae1101671890b707ea17732773905f185a81bc007
+  data.tar.gz: 5ac9dd843c6e837480dbc2fd6a00ecb6013e150a4c278e46ad75dafa1d8476973ac3e081125cd5ef678f5ba5fa5c6d2eb54676fc30fa258c870cd72833aa8a0d

data/README.md

@@ -23,6 +23,8 @@ AdvancedSelect is a small Rails engine for rendering an advanced select input wi
 - [Custom Option Content](#custom-option-content)
 - [Option Contract](#option-contract)
 - [Events](#events)
+- [Reading And Writing The Value](#reading-and-writing-the-value)
+- [Driving The Option List](#driving-the-option-list)
 - [Disabled State](#disabled-state)
 - [API Reference](#api-reference)
 - [Local Development](#local-development)
@@ -205,6 +207,30 @@ application.register("advanced-select", AdvancedSelectController)
 
 This keeps local custom behavior small while allowing future gem fixes to flow through the base controller.
 
+Two methods exist as extension points for host apps whose options endpoint does not speak Turbo
+Streams. `readOptionsResponse(response)` turns the `fetch` response into a payload and defaults to
+`response.text()`; `renderOptionsResponse(payload)` puts that payload on the page and defaults to
+`Turbo.renderStreamMessage(payload)`. Overriding them keeps the request sequencing, the stale
+response guard, and the post-render bookkeeping in the base controller:
+
+```js
+export default class extends AdvancedSelectController {
+  readOptionsResponse(response) {
+    return response.headers.get("content-type")?.includes("application/json")
+      ? response.json()
+      : super.readOptionsResponse(response)
+  }
+
+  renderOptionsResponse(payload) {
+    if (Array.isArray(payload)) {
+      this.replaceOptions(payload)
+    } else {
+      super.renderOptionsResponse(payload)
+    }
+  }
+}
+```
+
 For `jsbundling-rails` and other bundlers, the installer copies the full controller because bundlers do not resolve Rails engine JavaScript assets automatically. In that setup the copied file is host-owned.
 
 ### jsbundling/Propshaft Example
@@ -756,6 +782,22 @@ Every value change dispatches two events:
 | `change` | the first hidden input | native form behaviour and [dependent fields](#dependent-fields) |
 | `advanced-select:change` | the root element | application listeners that need the whole selection |
 
+A remote field also announces when its options finish rendering:
+
+| Event | Target | Purpose |
+| --- | --- | --- |
+| `advanced-select:options-loaded` | the root element | application listeners that react to the option list itself |
+
+It fires after every successful [remote](#remote-search) load — including eager
+[dependent](#dependent-fields) loads — once the options are in the DOM and any single-option
+auto-selection has been applied. Its `detail` carries the field `name`, the resulting `value`, and
+the `count` of selectable options, which is enough to react to an empty or single-option result
+without reading the DOM:
+
+```erb
+data-action="advanced-select:options-loaded->my-controller#optionsChanged"
+```
+
 Both bubble. `advanced-select:change` carries a `detail` payload:
 
 ```js
@@ -784,14 +826,70 @@ Prefer it over `change` on multiple selects. `change` is dispatched from the fir
 it does not fire at all once the last value is cleared from a field rendered with
 `include_hidden: false` — at that point the field has no inputs left.
 
-The current value is also readable from the controller:
+The current value is also readable from the controller — see [Reading And Writing The Value](#reading-and-writing-the-value).
+
+### Reading And Writing The Value
+
+The controller exposes the selection as a small programmatic API, so host code can drive a field
+without reaching into its markup:
 
 ```js
 const select = application.getControllerForElementAndIdentifier(element, "advanced-select")
 
-select.currentValue // => ["3", "7"]
+select.getValue()                              // => "7", or ["3", "7"] on a multiple select
+select.setValue("7")
+select.setValue(["3", "7"])                    // multiple selects also accept a single value
+select.setValue("7", { silent: true })         // assign without broadcasting a change
+select.refresh()                               // re-render from the current selection
+```
+
+`getValue` returns the submit value — the option's `value` when it defines one, otherwise its `id`.
+It is a string for single selects, an array for multiple selects, and empty when nothing is
+selected.
+
+`setValue` resolves each value against the options currently in the list, matching either the
+option's id or its submit value, so `setValue("identity-7")` and `setValue("submit-7")` select the
+same row. A value that matches no option is still assigned and submitted, using the value itself as
+the label — this keeps a server-assigned value from being silently dropped. Passing `""`, `null`, or
+`[]` clears the field. On a single select only the first value of an array is kept.
+
+`silent: true` suppresses the `change` and `advanced-select:change` events for that one assignment.
+Use it when the value is being restored rather than chosen — replacing options after a Turbo Stream
+update, for example — so dependent fields do not cascade off a change the user did not make. The
+suppression lasts for a single render; the next assignment broadcasts normally.
+
+### Driving The Option List
+
+The option list can be driven from the browser as well, for host apps that load options from
+somewhere the Turbo Stream flow does not cover:
+
+```js
+select.appendOption({ id: "9", label: "Item C" })
+
+select.replaceOptions([
+  { id: "3", label: "Item A" },
+  { id: "7", label: "Item B" }
+])
+
+select.replaceOptions(options, { selected: "7" })       // replace the list and set the value
+select.replaceOptions(options, { selected: null })      // replace the list and clear the value
+select.replaceOptions(options, { silent: false })       // broadcast the resulting value
 ```
 
+Both take options in the [option contract](#option-contract) shape and render them through
+`optionElement`, so they carry the host's class map.
+
+`appendOption` adds one option to the end of the list and does nothing if an option with that id is
+already there. It does not select the option — that is `addOption`, which exists for
+[Add Mode](#add-mode), where the user creates a value that was not in the list.
+
+`replaceOptions` swaps the whole list. Leaving `selected` out keeps the current selection, even when
+the new list no longer contains it — the common case after a search, where the selected record may
+have fallen outside the page of results. Passing `selected` assigns it with `setValue` semantics.
+
+Unlike `setValue`, `replaceOptions` is silent by default: replacing a list is not a value change, so
+it should not cascade to dependent fields on its own. Pass `silent: false` when it should.
+
 ### Disabled State
 
 Pass `disabled: true` to lock a field. It still renders its current selection —
@@ -1013,6 +1111,16 @@ Tailwind content scanning can usually see class strings when they are written li
 
 The host app can still load the gem CSS through `application.css`. `classes:` entries replace the mapped default classes for that helper call; unmapped keys keep the gem defaults. `append_classes:` entries keep the resolved class and append host classes after it.
 
+The resolved `option`, `option_check`, `option_content`, and `option_description` classes are also published on the root element as data attributes, so options the controller builds in the browser carry the same classes as the ones the server renders. `optionElement(option)` returns such an element:
+
+```js
+const select = application.getControllerForElementAndIdentifier(element, "advanced-select")
+
+select.currentOptionsTarget.appendChild(select.optionElement({ id: "7", label: "Item B" }))
+```
+
+It produces the same markup as `advanced_select_option_tag`: the option contract's `id`, `value`, `label`, `display_label`, and `description` are all honored, and the resulting element is fully interactive — hovering activates it and clicking selects it.
+
 ### CSS Overrides
 
 Importmap/Sprockets host applications can put app-specific styling in a host-owned file such as:

data/app/javascript/advanced_select/advanced_select_controller.js

@@ -30,6 +30,7 @@ export default class extends Controller {
     this.timer = null
     this.requestSequence = 0
     this.activeIndex = -1
+    this.suppressChange = false
     this.placeholderClass = this.element.dataset.advancedSelectPlaceholderClass || "ui-advanced-select-placeholder"
     this.valueClass = this.element.dataset.advancedSelectValueClass || "ui-advanced-select-value"
     this.tokenClass = this.element.dataset.advancedSelectTokenClass || "ui-advanced-select-token"
@@ -40,6 +41,10 @@ export default class extends Controller {
     this.optionActiveClasses = this.classList(this.element.dataset.advancedSelectOptionActiveClass || "ui-advanced-select-option-active")
     this.addOptionActiveClasses = this.classList(this.element.dataset.advancedSelectAddOptionActiveClass || "")
     this.optionSelectedClasses = this.classList(this.element.dataset.advancedSelectOptionSelectedClass || "")
+    this.optionClass = this.element.dataset.advancedSelectOptionClass || "ui-advanced-select-option"
+    this.optionCheckClass = this.element.dataset.advancedSelectOptionCheckClass || "ui-advanced-select-option-check"
+    this.optionContentClass = this.element.dataset.advancedSelectOptionContentClass || "ui-advanced-select-option-content"
+    this.optionDescriptionClass = this.element.dataset.advancedSelectOptionDescriptionClass || "ui-advanced-select-option-description"
     this.selectedValue = this.selectedValue.map((option) => this.normalizeSelectedOption(option))
     this.close = this.close.bind(this)
     this.renderOptionsState()
@@ -164,6 +169,55 @@ export default class extends Controller {
     this.close()
   }
 
+  getValue() {
+    return this.currentValue
+  }
+
+  setValue(value, { silent = false } = {}) {
+    const requested = (Array.isArray(value) ? value : [value])
+      .filter((item) => item !== "" && item != null)
+      .map(String)
+    const values = this.multipleValue ? requested : requested.slice(0, 1)
+    const options = this.optionElements.map((element) => this.optionData(element))
+
+    this.selectedValue = values.map((item) => {
+      const option = options.find((candidate) => candidate.id === item || candidate.value === item)
+
+      return this.normalizeSelectedOption(option || { id: item, value: item, label: item })
+    })
+
+    this.suppressChange = silent
+    this.renderSelection()
+  }
+
+  appendOption(option) {
+    const normalized = this.normalizeSelectedOption(option)
+    const present = this.optionElements.some((element) => element.dataset.advancedSelectValueParam === normalized.id)
+
+    if (present) {
+      return
+    }
+
+    this.currentOptionsTarget.appendChild(this.optionElement(normalized))
+    this.renderOptionsState()
+  }
+
+  replaceOptions(options, { selected, silent = true } = {}) {
+    this.currentOptionsTarget.replaceChildren(...options.map((option) => this.optionElement(option)))
+
+    if (selected === undefined) {
+      this.suppressChange = silent
+      this.renderSelection()
+      return
+    }
+
+    this.setValue(selected, { silent })
+  }
+
+  refresh() {
+    this.renderSelection()
+  }
+
   keydown(event) {
     if (event.key === "ArrowDown") {
       event.preventDefault()
@@ -265,14 +319,14 @@ export default class extends Controller {
           throw new Error("Advanced select options request failed")
         }
 
-        return response.text()
+        return this.readOptionsResponse(response)
       })
-      .then((html) => {
+      .then((payload) => {
         if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
-        Turbo.renderStreamMessage(html)
+        this.renderOptionsResponse(payload)
         requestAnimationFrame(() => {
           if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
             return
@@ -285,6 +339,8 @@ export default class extends Controller {
           if (autoSelect) {
             this.autoSelectSingle()
           }
+
+          this.dispatchOptionsLoaded()
         })
       })
       .catch(() => {
@@ -350,6 +406,37 @@ export default class extends Controller {
     }
   }
 
+  optionElement(option) {
+    const normalized = this.normalizeSelectedOption(option)
+    const button = document.createElement("button")
+
+    button.type = "button"
+    button.className = this.optionClass
+    button.setAttribute("role", "option")
+    button.setAttribute("aria-selected", "false")
+    button.dataset.advancedSelectOption = ""
+    button.dataset.action = "mouseenter->advanced-select#activateOption mousedown->advanced-select#choose"
+    button.dataset.advancedSelectValueParam = normalized.id
+    button.dataset.advancedSelectSubmitValueParam = normalized.value
+    button.dataset.advancedSelectLabelParam = normalized.label
+    button.dataset.advancedSelectDisplayLabelParam = normalized.displayLabel
+    button.dataset.advancedSelectOptionParam = JSON.stringify(normalized)
+
+    const check = this.textElement("span", this.optionCheckClass, "")
+    check.dataset.advancedSelectOptionCheck = ""
+
+    const content = this.textElement("span", this.optionContentClass, "")
+    content.appendChild(this.textElement("span", "", normalized.label))
+
+    if (normalized.description) {
+      content.appendChild(this.textElement("span", this.optionDescriptionClass, normalized.description))
+    }
+
+    button.append(check, content)
+
+    return button
+  }
+
   optionData(element) {
     const data = this.parseOptionData(element.dataset.advancedSelectOptionParam)
     const value = element.dataset.advancedSelectValueParam
@@ -402,7 +489,31 @@ export default class extends Controller {
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
     this.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
-    this.dispatchValueChange()
+
+    if (this.suppressChange) {
+      this.suppressChange = false
+    } else {
+      this.dispatchValueChange()
+    }
+  }
+
+  readOptionsResponse(response) {
+    return response.text()
+  }
+
+  renderOptionsResponse(payload) {
+    Turbo.renderStreamMessage(payload)
+  }
+
+  dispatchOptionsLoaded() {
+    this.element.dispatchEvent(new CustomEvent("advanced-select:options-loaded", {
+      bubbles: true,
+      detail: {
+        name: this.nameValue,
+        value: this.currentValue,
+        count: this.selectableOptionElements.length
+      }
+    }))
   }
 
   dispatchValueChange() {

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

@@ -29,6 +29,10 @@
      data-advanced-select-option-active-class="<%= advanced_select_state_class(class_map, :option_active) %>"
      data-advanced-select-add-option-active-class="<%= advanced_select_state_class(class_map, :add_option_active) %>"
      data-advanced-select-option-selected-class="<%= advanced_select_state_class(class_map, :option_selected) %>"
+     data-advanced-select-option-class="<%= advanced_select_class(class_map, :option) %>"
+     data-advanced-select-option-check-class="<%= advanced_select_class(class_map, :option_check) %>"
+     data-advanced-select-option-content-class="<%= advanced_select_class(class_map, :option_content) %>"
+     data-advanced-select-option-description-class="<%= advanced_select_class(class_map, :option_description) %>"
      data-advanced-select-selected-value="<%= advanced_select_selected_value(selected_options) %>">
   <div data-advanced-select-target="hiddenFields">
     <% if multiple %>

data/lib/advanced_select/version.rb

@@ -1,3 +1,3 @@
 module AdvancedSelect
-  VERSION = "0.1.10"
+  VERSION = "0.2.0"
 end

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

@@ -30,6 +30,7 @@ export default class extends Controller {
     this.timer = null
     this.requestSequence = 0
     this.activeIndex = -1
+    this.suppressChange = false
     this.placeholderClass = this.element.dataset.advancedSelectPlaceholderClass || "ui-advanced-select-placeholder"
     this.valueClass = this.element.dataset.advancedSelectValueClass || "ui-advanced-select-value"
     this.tokenClass = this.element.dataset.advancedSelectTokenClass || "ui-advanced-select-token"
@@ -40,6 +41,10 @@ export default class extends Controller {
     this.optionActiveClasses = this.classList(this.element.dataset.advancedSelectOptionActiveClass || "ui-advanced-select-option-active")
     this.addOptionActiveClasses = this.classList(this.element.dataset.advancedSelectAddOptionActiveClass || "")
     this.optionSelectedClasses = this.classList(this.element.dataset.advancedSelectOptionSelectedClass || "")
+    this.optionClass = this.element.dataset.advancedSelectOptionClass || "ui-advanced-select-option"
+    this.optionCheckClass = this.element.dataset.advancedSelectOptionCheckClass || "ui-advanced-select-option-check"
+    this.optionContentClass = this.element.dataset.advancedSelectOptionContentClass || "ui-advanced-select-option-content"
+    this.optionDescriptionClass = this.element.dataset.advancedSelectOptionDescriptionClass || "ui-advanced-select-option-description"
     this.selectedValue = this.selectedValue.map((option) => this.normalizeSelectedOption(option))
     this.close = this.close.bind(this)
     this.renderOptionsState()
@@ -164,6 +169,55 @@ export default class extends Controller {
     this.close()
   }
 
+  getValue() {
+    return this.currentValue
+  }
+
+  setValue(value, { silent = false } = {}) {
+    const requested = (Array.isArray(value) ? value : [value])
+      .filter((item) => item !== "" && item != null)
+      .map(String)
+    const values = this.multipleValue ? requested : requested.slice(0, 1)
+    const options = this.optionElements.map((element) => this.optionData(element))
+
+    this.selectedValue = values.map((item) => {
+      const option = options.find((candidate) => candidate.id === item || candidate.value === item)
+
+      return this.normalizeSelectedOption(option || { id: item, value: item, label: item })
+    })
+
+    this.suppressChange = silent
+    this.renderSelection()
+  }
+
+  appendOption(option) {
+    const normalized = this.normalizeSelectedOption(option)
+    const present = this.optionElements.some((element) => element.dataset.advancedSelectValueParam === normalized.id)
+
+    if (present) {
+      return
+    }
+
+    this.currentOptionsTarget.appendChild(this.optionElement(normalized))
+    this.renderOptionsState()
+  }
+
+  replaceOptions(options, { selected, silent = true } = {}) {
+    this.currentOptionsTarget.replaceChildren(...options.map((option) => this.optionElement(option)))
+
+    if (selected === undefined) {
+      this.suppressChange = silent
+      this.renderSelection()
+      return
+    }
+
+    this.setValue(selected, { silent })
+  }
+
+  refresh() {
+    this.renderSelection()
+  }
+
   keydown(event) {
     if (event.key === "ArrowDown") {
       event.preventDefault()
@@ -265,14 +319,14 @@ export default class extends Controller {
           throw new Error("Advanced select options request failed")
         }
 
-        return response.text()
+        return this.readOptionsResponse(response)
       })
-      .then((html) => {
+      .then((payload) => {
         if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
           return
         }
 
-        Turbo.renderStreamMessage(html)
+        this.renderOptionsResponse(payload)
         requestAnimationFrame(() => {
           if (!(eager || this.expanded) || requestSequence !== this.requestSequence) {
             return
@@ -285,6 +339,8 @@ export default class extends Controller {
           if (autoSelect) {
             this.autoSelectSingle()
           }
+
+          this.dispatchOptionsLoaded()
         })
       })
       .catch(() => {
@@ -350,6 +406,37 @@ export default class extends Controller {
     }
   }
 
+  optionElement(option) {
+    const normalized = this.normalizeSelectedOption(option)
+    const button = document.createElement("button")
+
+    button.type = "button"
+    button.className = this.optionClass
+    button.setAttribute("role", "option")
+    button.setAttribute("aria-selected", "false")
+    button.dataset.advancedSelectOption = ""
+    button.dataset.action = "mouseenter->advanced-select#activateOption mousedown->advanced-select#choose"
+    button.dataset.advancedSelectValueParam = normalized.id
+    button.dataset.advancedSelectSubmitValueParam = normalized.value
+    button.dataset.advancedSelectLabelParam = normalized.label
+    button.dataset.advancedSelectDisplayLabelParam = normalized.displayLabel
+    button.dataset.advancedSelectOptionParam = JSON.stringify(normalized)
+
+    const check = this.textElement("span", this.optionCheckClass, "")
+    check.dataset.advancedSelectOptionCheck = ""
+
+    const content = this.textElement("span", this.optionContentClass, "")
+    content.appendChild(this.textElement("span", "", normalized.label))
+
+    if (normalized.description) {
+      content.appendChild(this.textElement("span", this.optionDescriptionClass, normalized.description))
+    }
+
+    button.append(check, content)
+
+    return button
+  }
+
   optionData(element) {
     const data = this.parseOptionData(element.dataset.advancedSelectOptionParam)
     const value = element.dataset.advancedSelectValueParam
@@ -402,7 +489,31 @@ export default class extends Controller {
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
     this.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
-    this.dispatchValueChange()
+
+    if (this.suppressChange) {
+      this.suppressChange = false
+    } else {
+      this.dispatchValueChange()
+    }
+  }
+
+  readOptionsResponse(response) {
+    return response.text()
+  }
+
+  renderOptionsResponse(payload) {
+    Turbo.renderStreamMessage(payload)
+  }
+
+  dispatchOptionsLoaded() {
+    this.element.dispatchEvent(new CustomEvent("advanced-select:options-loaded", {
+      bubbles: true,
+      detail: {
+        name: this.nameValue,
+        value: this.currentValue,
+        count: this.selectableOptionElements.length
+      }
+    }))
   }
 
   dispatchValueChange() {

metadata

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