advanced_select 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f77cb8280bf5c4483c3d38f73628f8e17f7492f73684d4ced437f903198189b
-  data.tar.gz: 1baff77c13609cfc3c98770dbc7a8a6a2d67a2166ff04beca10e64aa7405e68c
+  metadata.gz: be334c14eaabfa7e2d3685deb4f1404b7187cb51c94d8a8dcb17b17e70bc5435
+  data.tar.gz: b9a676e2e4a64345631612285e8a362034b4efaaf60650cd201eadb2fa41b5a0
 SHA512:
-  metadata.gz: f184de3a7114166e60dd758b6f489191d9e9b469998c2deacb3446ad79992ddbc661f92dd492366acf718e77072b386b7da39c9d11022fac75b31ebfb9257f1e
-  data.tar.gz: c82e8749636458398cf8d9204cca3986bbff17785504833e18b28d87367209b1e67e99e98d2da07471a07429a8648d0237359d002dc480809190b945f6ea0a01
+  metadata.gz: be666dac14558aa5437cdf536c4bac3e8b392c61694904794a9d935de038152d6852c19e1d537a833f80836ae1101671890b707ea17732773905f185a81bc007
+  data.tar.gz: 5ac9dd843c6e837480dbc2fd6a00ecb6013e150a4c278e46ad75dafa1d8476973ac3e081125cd5ef678f5ba5fa5c6d2eb54676fc30fa258c870cd72833aa8a0d

data/README.md

@@ -23,6 +23,9 @@ 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)
 - [i18n](#i18n)
@@ -204,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
@@ -755,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
@@ -783,12 +826,111 @@ 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.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 —
+the point is to show the value, not to hide it — but it cannot be opened,
+searched, or cleared, and its value is **left out of the form**:
+
+```erb
+<%= advanced_select_tag(
+  "record[item_id]",
+  id: "record_item_id",
+  selected: selected_option,
+  options: options,
+  placeholder: "Choose an item",
+  disabled: true
+) %>
+```
+
+This matches a native `<select disabled>`: the browser omits a disabled field
+from the submitted params, so an update never writes a value the user was not
+allowed to change.
+
+The trigger carries the `disabled` attribute, so mouse and keyboard are both
+blocked by the browser rather than by CSS alone. The root element takes the
+`disabled` class from the class map.
+
+To toggle the state after render — from a Stimulus controller, or from a Turbo
+Stream that flips the attribute — set the value on the root element:
+
+```js
+element.dataset.advancedSelectDisabledValue = "true"
+```
+
+The controller reacts on its own: it disables the hidden inputs, applies the
+class, hides the clear control, and closes the dropdown if it happens to be
+open. The same thing is available as a method:
 
 ```js
 const select = application.getControllerForElementAndIdentifier(element, "advanced-select")
 
-select.currentValue // => ["3", "7"]
+select.disable()
+select.enable()
 ```
 
 ### API Reference
@@ -806,6 +948,7 @@ advanced_select_tag(
   multiple: false,
   searchable: true,
   add_mode: false,
+  disabled: false,
   dependent_fields: {},
   include_hidden: true,
   auto_select_single: true,
@@ -823,6 +966,8 @@ advanced_select_tag(
 
 `tooltip:` / `tooltip_partial:` enable an optional hover tooltip on the trigger (see [Selection Tooltip](#selection-tooltip)).
 
+`disabled:` locks the field (see [Disabled State](#disabled-state)).
+
 `advanced_select_options_tag`:
 
 ```ruby
@@ -966,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/assets/stylesheets/advanced_select/advanced_select.css

@@ -11,6 +11,16 @@
   display: none !important;
 }
 
+.ui-advanced-select-disabled .ui-advanced-select-trigger {
+  background: #f3f4f6;
+  color: #6b7280;
+  cursor: not-allowed;
+}
+
+.ui-advanced-select-disabled .ui-advanced-select-clear {
+  display: none;
+}
+
 .ui-advanced-select-trigger {
   align-items: center;
   background: #ffffff;

data/app/javascript/advanced_select/advanced_select_controller.js

@@ -8,6 +8,7 @@ export default class extends Controller {
     autoSelectSingle: { type: Boolean, default: true },
     delay: { type: Number, default: 200 },
     dependentFields: Object,
+    disabled: Boolean,
     eager: { type: Boolean, default: true },
     emptyText: String,
     errorText: String,
@@ -29,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"
@@ -39,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()
@@ -65,7 +71,40 @@ export default class extends Controller {
     this.expanded ? this.close() : this.open()
   }
 
+  disable() {
+    this.disabledValue = true
+  }
+
+  enable() {
+    this.disabledValue = false
+  }
+
+  disabledValueChanged() {
+    if (!this.hasTriggerTarget) {
+      return
+    }
+
+    const disabled = this.disabledValue
+    const classes = this.classList(this.element.dataset.advancedSelectDisabledClass || "ui-advanced-select-disabled")
+
+    this.triggerTarget.disabled = disabled
+    this.hiddenFieldsTarget.querySelectorAll("input").forEach((input) => { input.disabled = disabled })
+    this.clearTarget.classList.toggle("hidden", disabled || this.selectedValue.length === 0)
+
+    if (classes.length) {
+      disabled ? this.element.classList.add(...classes) : this.element.classList.remove(...classes)
+    }
+
+    if (disabled && this.expanded) {
+      this.close()
+    }
+  }
+
   open() {
+    if (this.disabledValue) {
+      return
+    }
+
     this.hideTooltip(true)
     this.dropdownTarget.classList.remove("hidden")
     this.triggerTarget.setAttribute("aria-expanded", "true")
@@ -120,11 +159,65 @@ export default class extends Controller {
   clear(event) {
     event.preventDefault()
     event.stopPropagation()
+
+    if (this.disabledValue) {
+      return
+    }
+
     this.selectedValue = []
     this.renderSelection()
     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()
@@ -226,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
@@ -246,6 +339,8 @@ export default class extends Controller {
           if (autoSelect) {
             this.autoSelectSingle()
           }
+
+          this.dispatchOptionsLoaded()
         })
       })
       .catch(() => {
@@ -311,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
@@ -362,8 +488,32 @@ export default class extends Controller {
     this.renderTooltip()
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
-    this.clearTarget.classList.toggle("hidden", this.selectedValue.length === 0)
-    this.dispatchValueChange()
+    this.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
+
+    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() {
@@ -515,6 +665,7 @@ export default class extends Controller {
       input.type = "hidden"
       input.name = this.nameValue
       input.value = option ? option.value || option.id : ""
+      input.disabled = this.disabledValue
 
       if (!this.multipleValue) {
         input.id = this.inputIdValue

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

@@ -1,5 +1,7 @@
-<div class="<%= advanced_select_class(class_map, :root) %>"
+<div class="<%= advanced_select_class(class_map, :root, (:disabled if disabled)) %>"
      data-controller="advanced-select"
+     data-advanced-select-disabled-value="<%= disabled %>"
+     data-advanced-select-disabled-class="<%= advanced_select_state_class(class_map, :disabled) %>"
      data-advanced-select-url-value="<%= options_url %>"
      data-advanced-select-target-id-value="<%= target_id %>"
      data-advanced-select-name-value="<%= name %>"
@@ -27,17 +29,21 @@
      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 %>
       <% if include_hidden %>
-        <%= hidden_field_tag name, "", id: nil %>
+        <%= hidden_field_tag name, "", id: nil, disabled: disabled %>
       <% end %>
       <% selected_options.each do |option| %>
-        <%= hidden_field_tag name, option.fetch(:value, option.fetch(:id)) %>
+        <%= hidden_field_tag name, option.fetch(:value, option.fetch(:id)), disabled: disabled %>
       <% end %>
     <% else %>
-      <%= hidden_field_tag name, selected_options.first&.fetch(:value, selected_options.first&.fetch(:id)), id: id %>
+      <%= hidden_field_tag name, selected_options.first&.fetch(:value, selected_options.first&.fetch(:id)), id: id, disabled: disabled %>
     <% end %>
   </div>
 
@@ -49,13 +55,14 @@
           aria-haspopup="listbox"
           aria-expanded="false"
           aria-controls="<%= "#{id}_dropdown" %>"
+          <%= "disabled" if disabled %>
           data-advanced-select-target="trigger"
           data-action="advanced-select#toggle keydown->advanced-select#keydown<%= " mouseenter->advanced-select#showTooltip mouseleave->advanced-select#hideTooltip" if tooltip_enabled %>">
     <span id="<%= "#{id}_summary" %>" class="<%= advanced_select_class(class_map, :summary) %>" data-advanced-select-target="summary">
       <%= render partial: "advanced_select/summary", locals: { selected_options: selected_options, multiple: multiple, placeholder: placeholder, summary_mode: summary_mode, class_map: class_map } %>
     </span>
     <span id="<%= "#{id}_caret" %>" class="<%= [advanced_select_class(class_map, :caret), ("hidden" if selected_options.any?)].compact.join(" ") %>" data-advanced-select-target="caret">&#8964;</span>
-    <span id="<%= "#{id}_clear" %>" class="<%= [advanced_select_class(class_map, :clear), ("hidden" if selected_options.empty?)].compact.join(" ") %>" data-advanced-select-target="clear" data-action="click->advanced-select#clear">&times;</span>
+    <span id="<%= "#{id}_clear" %>" class="<%= [advanced_select_class(class_map, :clear), ("hidden" if disabled || selected_options.empty?)].compact.join(" ") %>" data-advanced-select-target="clear" data-action="click->advanced-select#clear">&times;</span>
   </button>
 
   <% if tooltip_enabled %>

data/lib/advanced_select/class_map.rb

@@ -2,6 +2,7 @@ module AdvancedSelect
   class ClassMap
     DEFAULTS = {
       root: "ui-advanced-select",
+      disabled: "ui-advanced-select-disabled",
       trigger: "ui-advanced-select-trigger",
       summary: "ui-advanced-select-summary",
       placeholder: "ui-advanced-select-placeholder",

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, auto_select_single: true, eager: true, summary_mode: :tokens, tooltip: false, tooltip_partial: nil, 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, disabled: false, dependent_fields: {}, include_hidden: true, auto_select_single: true, eager: true, summary_mode: :tokens, tooltip: false, tooltip_partial: nil, option_content_partial: nil, classes: {}, append_classes: {})
       selected_options = advanced_select_selected_options(selected)
       class_map = advanced_select_class_map(classes, append_classes)
 
@@ -14,6 +14,7 @@ module AdvancedSelect
         multiple: multiple,
         searchable: searchable,
         add_mode: add_mode,
+        disabled: disabled,
         dependent_fields: dependent_fields,
         include_hidden: include_hidden,
         auto_select_single: auto_select_single,

data/lib/advanced_select/version.rb

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

data/lib/generators/advanced_select/install/templates/advanced_select.css

@@ -11,6 +11,16 @@
   display: none !important;
 }
 
+.ui-advanced-select-disabled .ui-advanced-select-trigger {
+  background: #f3f4f6;
+  color: #6b7280;
+  cursor: not-allowed;
+}
+
+.ui-advanced-select-disabled .ui-advanced-select-clear {
+  display: none;
+}
+
 .ui-advanced-select-trigger {
   align-items: center;
   background: #ffffff;

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

@@ -8,6 +8,7 @@ export default class extends Controller {
     autoSelectSingle: { type: Boolean, default: true },
     delay: { type: Number, default: 200 },
     dependentFields: Object,
+    disabled: Boolean,
     eager: { type: Boolean, default: true },
     emptyText: String,
     errorText: String,
@@ -29,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"
@@ -39,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()
@@ -65,7 +71,40 @@ export default class extends Controller {
     this.expanded ? this.close() : this.open()
   }
 
+  disable() {
+    this.disabledValue = true
+  }
+
+  enable() {
+    this.disabledValue = false
+  }
+
+  disabledValueChanged() {
+    if (!this.hasTriggerTarget) {
+      return
+    }
+
+    const disabled = this.disabledValue
+    const classes = this.classList(this.element.dataset.advancedSelectDisabledClass || "ui-advanced-select-disabled")
+
+    this.triggerTarget.disabled = disabled
+    this.hiddenFieldsTarget.querySelectorAll("input").forEach((input) => { input.disabled = disabled })
+    this.clearTarget.classList.toggle("hidden", disabled || this.selectedValue.length === 0)
+
+    if (classes.length) {
+      disabled ? this.element.classList.add(...classes) : this.element.classList.remove(...classes)
+    }
+
+    if (disabled && this.expanded) {
+      this.close()
+    }
+  }
+
   open() {
+    if (this.disabledValue) {
+      return
+    }
+
     this.hideTooltip(true)
     this.dropdownTarget.classList.remove("hidden")
     this.triggerTarget.setAttribute("aria-expanded", "true")
@@ -120,11 +159,65 @@ export default class extends Controller {
   clear(event) {
     event.preventDefault()
     event.stopPropagation()
+
+    if (this.disabledValue) {
+      return
+    }
+
     this.selectedValue = []
     this.renderSelection()
     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()
@@ -226,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
@@ -246,6 +339,8 @@ export default class extends Controller {
           if (autoSelect) {
             this.autoSelectSingle()
           }
+
+          this.dispatchOptionsLoaded()
         })
       })
       .catch(() => {
@@ -311,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
@@ -362,8 +488,32 @@ export default class extends Controller {
     this.renderTooltip()
     this.renderOptionsState()
     this.caretTarget.classList.toggle("hidden", this.selectedValue.length > 0)
-    this.clearTarget.classList.toggle("hidden", this.selectedValue.length === 0)
-    this.dispatchValueChange()
+    this.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
+
+    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() {
@@ -515,6 +665,7 @@ export default class extends Controller {
       input.type = "hidden"
       input.name = this.nameValue
       input.value = option ? option.value || option.id : ""
+      input.disabled = this.disabledValue
 
       if (!this.multipleValue) {
         input.id = this.inputIdValue

metadata

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