From 5aae4545d5636356af8e20efbab7e8124034caba Mon Sep 17 00:00:00 2001
From: "ulsyemr@gmail.com" <ulsyemr@gmail.com>
Date: Wed, 12 Aug 2026 23:25:16 +0300
Subject: [PATCH 1/3] Add a disabled state that locks the field and omits it
 from the form

---
 README.md                                     | 47 +++++++++++
 .../advanced_select/advanced_select.css       | 10 +++
 .../advanced_select_controller.js             | 42 +++++++++-
 app/views/advanced_select/_select.html.erb    | 13 +--
 lib/advanced_select/class_map.rb              |  1 +
 lib/advanced_select/helper.rb                 |  3 +-
 .../install/templates/advanced_select.css     | 10 +++
 .../templates/advanced_select_controller.js   | 42 +++++++++-
 .../advanced_select_examples/show.html.erb    | 13 +++
 .../advanced_select_interaction_test.rb       | 82 +++++++++++++++++++
 10 files changed, 255 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index c719da4..62d2139 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ 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)
+- [Disabled State](#disabled-state)
 - [API Reference](#api-reference)
 - [Local Development](#local-development)
 - [i18n](#i18n)
@@ -791,6 +792,49 @@ const select = application.getControllerForElementAndIdentifier(element, "advanc
 select.currentValue // => ["3", "7"]
 ```
 
+### 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.disable()
+select.enable()
+```
+
 ### API Reference
 
 `advanced_select_tag`:
@@ -806,6 +850,7 @@ advanced_select_tag(
   multiple: false,
   searchable: true,
   add_mode: false,
+  disabled: false,
   dependent_fields: {},
   include_hidden: true,
   auto_select_single: true,
@@ -823,6 +868,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
diff --git a/app/assets/stylesheets/advanced_select/advanced_select.css b/app/assets/stylesheets/advanced_select/advanced_select.css
index 539e409..21ad4c4 100644
--- a/app/assets/stylesheets/advanced_select/advanced_select.css
+++ b/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;
diff --git a/app/javascript/advanced_select/advanced_select_controller.js b/app/javascript/advanced_select/advanced_select_controller.js
index a8bdf3c..2646ff5 100644
--- a/app/javascript/advanced_select/advanced_select_controller.js
+++ b/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,
@@ -65,7 +66,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,6 +154,11 @@ export default class extends Controller {
   clear(event) {
     event.preventDefault()
     event.stopPropagation()
+
+    if (this.disabledValue) {
+      return
+    }
+
     this.selectedValue = []
     this.renderSelection()
     this.close()
@@ -362,7 +401,7 @@ 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.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
     this.dispatchValueChange()
   }
 
@@ -515,6 +554,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
diff --git a/app/views/advanced_select/_select.html.erb b/app/views/advanced_select/_select.html.erb
index 10349ad..648f8be 100644
--- a/app/views/advanced_select/_select.html.erb
+++ b/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 %>"
@@ -31,13 +33,13 @@
   <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 +51,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 %>
diff --git a/lib/advanced_select/class_map.rb b/lib/advanced_select/class_map.rb
index ca620e9..61b2246 100644
--- a/lib/advanced_select/class_map.rb
+++ b/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",
diff --git a/lib/advanced_select/helper.rb b/lib/advanced_select/helper.rb
index 57ec7d8..b1b3e69 100644
--- a/lib/advanced_select/helper.rb
+++ b/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 @@ def advanced_select_tag(name, id:, selected:, options:, placeholder:, options_ur
         multiple: multiple,
         searchable: searchable,
         add_mode: add_mode,
+        disabled: disabled,
         dependent_fields: dependent_fields,
         include_hidden: include_hidden,
         auto_select_single: auto_select_single,
diff --git a/lib/generators/advanced_select/install/templates/advanced_select.css b/lib/generators/advanced_select/install/templates/advanced_select.css
index 539e409..21ad4c4 100644
--- a/lib/generators/advanced_select/install/templates/advanced_select.css
+++ b/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;
diff --git a/lib/generators/advanced_select/install/templates/advanced_select_controller.js b/lib/generators/advanced_select/install/templates/advanced_select_controller.js
index a8bdf3c..2646ff5 100644
--- a/lib/generators/advanced_select/install/templates/advanced_select_controller.js
+++ b/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,
@@ -65,7 +66,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,6 +154,11 @@ export default class extends Controller {
   clear(event) {
     event.preventDefault()
     event.stopPropagation()
+
+    if (this.disabledValue) {
+      return
+    }
+
     this.selectedValue = []
     this.renderSelection()
     this.close()
@@ -362,7 +401,7 @@ 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.clearTarget.classList.toggle("hidden", this.disabledValue || this.selectedValue.length === 0)
     this.dispatchValueChange()
   }
 
@@ -515,6 +554,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
diff --git a/test/dummy/app/views/advanced_select_examples/show.html.erb b/test/dummy/app/views/advanced_select_examples/show.html.erb
index 3206b1e..9f66a49 100644
--- a/test/dummy/app/views/advanced_select_examples/show.html.erb
+++ b/test/dummy/app/views/advanced_select_examples/show.html.erb
@@ -270,3 +270,16 @@
   classes: styled_advanced_select_classes,
   append_classes: styled_advanced_select_append_classes
 ) %>
+
+<%= advanced_select_tag(
+  "example[disabled_id]",
+  id: "example_disabled_id",
+  selected: { id: "disabled-1", label: "Disabled One" },
+  options: [
+    { id: "disabled-1", label: "Disabled One" },
+    { id: "disabled-2", label: "Disabled Two" }
+  ],
+  placeholder: "Choose disabled item",
+  disabled: true,
+  searchable: false
+) %>
diff --git a/test/system/advanced_select_interaction_test.rb b/test/system/advanced_select_interaction_test.rb
index 27000af..8495017 100644
--- a/test/system/advanced_select_interaction_test.rb
+++ b/test/system/advanced_select_interaction_test.rb
@@ -395,6 +395,76 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
     assert_equal [[]], advanced_select_events.map { |event| event["value"] }
   end
 
+  test "renders its selection but cannot be opened while disabled" do
+    visit root_path
+
+    assert_selector ".ui-advanced-select-disabled #example_disabled_id_trigger[disabled]"
+    assert_selector "#example_disabled_id_summary", text: "Disabled One"
+    assert_equal "none", dropdown_display("example_disabled_id")
+
+    page.execute_script("document.getElementById('example_disabled_id_trigger').click()")
+
+    assert_equal "none", dropdown_display("example_disabled_id")
+  end
+
+  test "leaves a disabled value out of the form" do
+    visit root_path
+
+    assert_selector "input[name='example[disabled_id]'][value='disabled-1'][disabled]", visible: false
+  end
+
+  test "hides the clear control while disabled" do
+    visit root_path
+
+    assert_no_selector "#example_disabled_id_clear", visible: true
+  end
+
+  test "enabling at runtime restores interaction and form submission" do
+    visit root_path
+    set_disabled("example_disabled_id", false)
+
+    assert_no_selector ".ui-advanced-select-disabled #example_disabled_id_trigger"
+    assert_no_selector "input[name='example[disabled_id]'][disabled]", visible: false
+
+    find("#example_disabled_id_trigger").click
+    find("#example_disabled_id_options button", text: "Disabled Two").click
+
+    assert_selector "#example_disabled_id_summary", text: "Disabled Two"
+    assert_selector "input[name='example[disabled_id]'][value='disabled-2']", visible: false
+    assert_no_selector "input[name='example[disabled_id]'][disabled]", visible: false
+  end
+
+  test "disabling at runtime closes the dropdown and drops the value from the form" do
+    visit root_path
+
+    find("#example_item_id_trigger").click
+
+    assert_selector "#example_item_id_options button", text: "Local One"
+
+    set_disabled("example_item_id", true)
+
+    assert_equal "none", dropdown_display("example_item_id")
+    assert_selector ".ui-advanced-select-disabled #example_item_id_trigger[disabled]"
+    assert_selector "input[name='example[item_id]'][disabled]", visible: false
+  end
+
+  test "disabling at runtime hides the clear control and enabling brings it back" do
+    visit root_path
+
+    find("#example_item_id_trigger").click
+    find("#example_item_id_options button", text: "Local One").click
+
+    assert_selector "#example_item_id_clear", visible: true
+
+    set_disabled("example_item_id", true)
+
+    assert_no_selector "#example_item_id_clear", visible: true
+
+    set_disabled("example_item_id", false)
+
+    assert_selector "#example_item_id_clear", visible: true
+  end
+
   private
 
   def record_advanced_select_events
@@ -410,6 +480,18 @@ def advanced_select_events
     page.evaluate_script("window.__advancedSelectEvents")
   end
 
+  def dropdown_display(select_id)
+    page.evaluate_script("getComputedStyle(document.getElementById('#{select_id}_dropdown')).display")
+  end
+
+  def set_disabled(select_id, disabled)
+    page.execute_script(<<~JS)
+      document.getElementById("#{select_id}_trigger")
+              .closest("[data-controller~='advanced-select']")
+              .dataset.advancedSelectDisabledValue = "#{disabled}"
+    JS
+  end
+
   def assert_selected_option_check(select_id, text)
     option = find("##{select_id}_options button[aria-selected='true']", text: text)
 

From 094c5b8626ef8d6c8551a3d9e1f0e252558885f7 Mon Sep 17 00:00:00 2001
From: "ulsyemr@gmail.com" <ulsyemr@gmail.com>
Date: Wed, 12 Aug 2026 23:33:37 +0300
Subject: [PATCH 2/3] Scope the recorded change events to the field under test

---
 test/system/advanced_select_interaction_test.rb | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/test/system/advanced_select_interaction_test.rb b/test/system/advanced_select_interaction_test.rb
index 8495017..9301eac 100644
--- a/test/system/advanced_select_interaction_test.rb
+++ b/test/system/advanced_select_interaction_test.rb
@@ -342,7 +342,7 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
 
   test "broadcasts advanced-select:change with the selected value" do
     visit root_path
-    record_advanced_select_events
+    record_advanced_select_events("example[item_id]")
 
     find("#example_item_id_trigger").click
     find("#example_item_id_options button", text: "Local One").click
@@ -359,7 +359,7 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
 
   test "broadcasts the submit value rather than the option id" do
     visit root_path
-    record_advanced_select_events
+    record_advanced_select_events("example[submit_id]")
 
     find("#example_submit_id_trigger").click
     find("#example_submit_id_options button", text: "Submit Item").click
@@ -370,7 +370,7 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
 
   test "broadcasts an array of values for multiple selects" do
     visit root_path
-    record_advanced_select_events
+    record_advanced_select_events("example[multiple_ids][]")
 
     find("#example_multiple_ids_trigger").click
     find("#example_multiple_ids_options button", text: "Multi One").click
@@ -388,7 +388,7 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
 
     assert_selector "input[name='example[multiple_ids_without_blank][]'][value='multi-1']", visible: false
 
-    record_advanced_select_events
+    record_advanced_select_events("example[multiple_ids_without_blank][]")
     find("#example_multiple_ids_without_blank_clear").click
 
     assert_no_selector "input[name='example[multiple_ids_without_blank][]']", visible: false
@@ -467,11 +467,13 @@ class AdvancedSelectInteractionTest < ApplicationSystemTestCase
 
   private
 
-  def record_advanced_select_events
+  def record_advanced_select_events(name)
     page.execute_script(<<~JS)
       window.__advancedSelectEvents = []
       document.addEventListener("advanced-select:change", (event) => {
-        window.__advancedSelectEvents.push(event.detail)
+        if (event.detail.name === "#{name}") {
+          window.__advancedSelectEvents.push(event.detail)
+        }
       })
     JS
   end

From 2d7df21ff15f8b2e2874575a2d25e0b64ef11be0 Mon Sep 17 00:00:00 2001
From: "ulsyemr@gmail.com" <ulsyemr@gmail.com>
Date: Thu, 13 Aug 2026 10:28:13 +0300
Subject: [PATCH 3/3] Bump version to 0.1.10

---
 Gemfile.lock                   | 2 +-
 lib/advanced_select/version.rb | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index 9010f6a..eae2dde 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    advanced_select (0.1.9)
+    advanced_select (0.1.10)
       actionview (>= 7.1)
       railties (>= 7.1)
       stimulus-rails (>= 1.3)
diff --git a/lib/advanced_select/version.rb b/lib/advanced_select/version.rb
index 6ccbe37..7470a2d 100644
--- a/lib/advanced_select/version.rb
+++ b/lib/advanced_select/version.rb
@@ -1,3 +1,3 @@
 module AdvancedSelect
-  VERSION = "0.1.9"
+  VERSION = "0.1.10"
 end