advanced_select 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d986f80cf90e0dc2aa254d9eb0a9b8d76b844f205ae8ca86f815c1a5b17bea
-  data.tar.gz: 72722ff9f42bbed846afe1ec04e46362e9ec259d96c7bacb171207dd8ccbdc79
+  metadata.gz: 3268b609f1b4c08af63c6bc791459345dbbdfb1afa3a1e9974569392e27b417a
+  data.tar.gz: 525a23db2449fd8867d83fb7b1647d75d6d194a4791971fec0cb55de48a2d1c8
 SHA512:
-  metadata.gz: d287e5b91c20d5dd629d55f802f1095fd2f016e3f4bdccff8f011fabf0e115914d56563ed00f5219a7a65452d1df4b143a4f2b3e5bf68b8ebb93898c83a7910d
-  data.tar.gz: 1b9d260a2ace0a2ec7d132581da98e35a09fc26265420655afa40ff290454b716584bb1cf5062a5ce2fa1a432cae22c1da75e411546b3673e88e468b4295910e
+  metadata.gz: f66187ab2d1914f3de4c933fecbf3b9237684b4c8d911de1582426002f6d099820181401137d6c0896d3cdb99b1af38ecf12acbdd8dd29ff7aac6af965e2c587
+  data.tar.gz: 3a240d713742fcd791541b4272e499d6036d8ada44eb8697529628d9b1ceb9092678362bf435bcd25bc8b33d95e6f9a95d4a752e23b9b587fe814b738ddb9cd6

data/README.md

@@ -22,6 +22,8 @@ AdvancedSelect is a small Rails engine for rendering an advanced select input wi
 - [Dependent Fields](#dependent-fields)
 - [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)
@@ -745,6 +747,94 @@ Grouped options use this shape:
 ]
 ```
 
+### Events
+
+Every value change dispatches two events:
+
+| Event | Target | Purpose |
+| --- | --- | --- |
+| `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 |
+
+Both bubble. `advanced-select:change` carries a `detail` payload:
+
+```js
+{
+  name: "record[item_ids][]",
+  value: ["3", "7"],
+  options: [
+    { id: "3", value: "3", label: "Item A", display_label: "Item A" },
+    { id: "7", value: "7", label: "Item B", display_label: "Item B" }
+  ]
+}
+```
+
+`value` is the submit value — the option's `value` when it defines one, otherwise its `id`. It is an
+array for multiple selects, a string for single selects, and empty when nothing is selected. A
+multiple select lists the most recently chosen option first, matching the order of its hidden
+inputs.
+
+Bind it like any other event:
+
+```erb
+data-action="advanced-select:change->my-controller#refresh"
+```
+
+Prefer it over `change` on multiple selects. `change` is dispatched from the first hidden input, so
+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:
+
+```js
+const select = application.getControllerForElementAndIdentifier(element, "advanced-select")
+
+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`:
@@ -760,6 +850,7 @@ advanced_select_tag(
   multiple: false,
   searchable: true,
   add_mode: false,
+  disabled: false,
   dependent_fields: {},
   include_hidden: true,
   auto_select_single: true,
@@ -777,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

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,
@@ -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()
   }
 
@@ -371,6 +410,21 @@ export default class extends Controller {
     if (input) {
       input.dispatchEvent(new Event("change", { bubbles: true }))
     }
+
+    this.element.dispatchEvent(new CustomEvent("advanced-select:change", {
+      bubbles: true,
+      detail: {
+        name: this.nameValue,
+        value: this.currentValue,
+        options: [...this.selectedValue]
+      }
+    }))
+  }
+
+  get currentValue() {
+    const values = this.selectedValue.map((option) => option.value || option.id)
+
+    return this.multipleValue ? values : (values[0] || "")
   }
 
   renderOptionsState() {
@@ -500,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

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 %>"
@@ -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 %>

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.8"
+  VERSION = "0.1.10"
 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,
@@ -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()
   }
 
@@ -371,6 +410,21 @@ export default class extends Controller {
     if (input) {
       input.dispatchEvent(new Event("change", { bubbles: true }))
     }
+
+    this.element.dispatchEvent(new CustomEvent("advanced-select:change", {
+      bubbles: true,
+      detail: {
+        name: this.nameValue,
+        value: this.currentValue,
+        options: [...this.selectedValue]
+      }
+    }))
+  }
+
+  get currentValue() {
+    const values = this.selectedValue.map((option) => option.value || option.id)
+
+    return this.multipleValue ? values : (values[0] || "")
   }
 
   renderOptionsState() {
@@ -500,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

metadata

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