layered-ui-rails 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffb58ab0d1712c81928bbf3685708f5571e98dd1af70484024219dc6a491f2cc
-  data.tar.gz: 495f951c875f7572f38b77e6739fcbd49856160a0d84e96cd76f701c97d1262d
+  metadata.gz: d892f7efaed58d161179cc5478eaf0961b4b31c2e822aaba4063143343aeac31
+  data.tar.gz: 28e37164714d1a354b255a10a3833069b94f6202480082b29e70fcc23a485ffa
 SHA512:
-  metadata.gz: 4f855f052b32a2b172a8bb390d1bd19680fccc568996a9b286c4edf9eec2665ad3e0c97b8ff686d760da9dd8f9306ef941cb1ed449f65b984ac01d139818230d
-  data.tar.gz: a0abb3efe8343044f8581ad5f1c476f3a822c7225daf3ec5638d4a61cb685d5db3886f7f884d461ab685a4b8ff67f68894fca25324665219051ebd439a6a428a
+  metadata.gz: d2d3c833c03dd9c56d88bf578fb69f27ddf0eda03baf31ebb0953e6de0bb9b5ae1248d444e77c362d18e4288aad6adbae28a4959f95c68a392b373417c23040d
+  data.tar.gz: 661964c07f3d03e1d4ee937a9f4b3f3d456491fadb9ee67778cee063d9eda535fbf02a276bcfe1a3c0a1b67579ece03afda66a5e1d98c90ebe6b232de6c05731

data/.claude/skills/layered-ui-rails/references/HELPERS.md

@@ -257,14 +257,21 @@ Renders a complete form with all fields, error summary, and submit button via th
 
 Field options:
 - `attribute` (Symbol) - model attribute
-- `as` (Symbol, optional) - field type; auto-detected from column type. Supported: `:string`, `:text`, `:email`, `:password`, `:number`, `:tel`, `:url`, `:search`, `:date`, `:datetime`, `:time`, `:month`, `:week`, `:color`, `:range`, `:file`, `:select`, `:checkbox`, `:hidden`. Forms automatically become `multipart` when any field is `:file`.
+- `as` (Symbol, optional) - field type; auto-detected from column type. Supported: `:string`, `:text`, `:email`, `:password`, `:number`, `:tel`, `:url`, `:search`, `:date`, `:datetime`, `:time`, `:month`, `:week`, `:color`, `:range`, `:file`, `:select`, `:combobox`, `:checkbox`, `:hidden`. Forms automatically become `multipart` when any field is `:file`.
 - `label` (String, optional) - custom label text; defaults to humanised attribute
 - `required` (Boolean, optional) - marks field as required; default false
 - `hint` (String, optional) - help text below the field
-- `collection` (Array, optional) - required for `:select` type; e.g. `[['Label', value], ...]`
+- `collection` (Array, optional) - required for `:select`; for `:combobox` either this or `url:` is required; e.g. `[['Label', value], ...]`
 - `include_blank` (Boolean or String, optional) - for `:select` fields; defaults to `true`. Pass a string to use as the blank option's label, or `false` to omit it. Suppressed when `prompt:` is set
 - `prompt` (String, optional) - for `:select` fields; prompt text shown as the first option, only selectable when no value is set
 - `placeholder` (String, optional) - input placeholder text
+- any other key passes through to the underlying field helper as an HTML attribute (`:combobox` excepted - see below)
+
+A `:combobox` field renders its own label and hint, adds the field's error element to its `aria-describedby`, and defaults `selected:` to the record's current value. That, and its keyword-only signature, give three rules:
+
+- It takes only `l_ui_combobox`'s own options - `url:`, `multiple:`, `create:`, `create_name:`, `reorder:`, `min_chars:`, `text:`, `selected:`, `disabled:`, `describedby:`, `container:`, `id:`. Every other key raises, `prompt:` and `include_blank:` included; extra HTML attributes go on `container:`.
+- `multiple:` is inferred from the attribute rather than defaulting to `l_ui_combobox`'s `true`: an `_ids` attribute, an array column, or one already holding an array is multiple; anything else is single, so a scalar attribute posts a scalar rather than an array Active Record would cast to `nil`. Pass `multiple:` explicitly to override.
+- Pass `selected: [[@post.user.name, @post.user_id]]` whenever the record's value might not be in the options - a `url:` collection never holds it, and nor does a scoped, paginated or filtered `collection:`. Without it, the field raises on an edit form.
 
 ```erb
 <%= l_ui_form(@post,
@@ -273,6 +280,8 @@ Field options:
     { attribute: :body, as: :text },
     { attribute: :category, as: :select, collection: Category.pluck(:name, :id) },
     { attribute: :published, as: :checkbox },
+    { attribute: :tag_ids, as: :combobox, collection: Tag.pluck(:name, :id) },
+    { attribute: :author_id, as: :combobox, url: options_users_path },
   ],
   url: posts_path) %>
 ```
@@ -284,6 +293,7 @@ l_ui_normalise_field(record, config)  # Normalise a raw field config into canoni
 l_ui_field_error_id(record, attribute)  # Error element ID for aria-describedby
 l_ui_field_hint_id(record, attribute)   # Hint element ID for aria-describedby
 l_ui_field_describedby(record, attribute, hint: false)  # Space-joined hint + error IDs for aria-describedby
+l_ui_field_value(record, attribute)     # Record's current value; default :combobox selection
 ```
 
 ## Modal
@@ -415,7 +425,7 @@ When a popover is declared, the tag container itself becomes the `l-ui--popover`
 l_ui_combobox(name, collection: nil, form: nil, selected: nil, multiple: true,
               create: false, create_name: nil, reorder: false, url: nil,
               min_chars: 0, text: {}, id: nil, label: nil, hint: nil, placeholder: nil,
-              required: false, disabled: false, container: {})
+              required: false, disabled: false, describedby: nil, container: {})
 ```
 
 Renders a token select (`class="l-ui-combobox"`): a text input with type-ahead filtering whose selections become removable tags, in the style of an email recipient field. Built on the ARIA combobox pattern - no third-party select library.
@@ -431,8 +441,11 @@ Renders a token select (`class="l-ui-combobox"`): a text input with type-ahead f
 - `url` (String, optional) - endpoint searched as the user types; options come from it rather than from `collection:`
 - `min_chars` (Integer, default `0`) - characters needed before a remote search runs; `0` searches as soon as the field is focused
 - `text` (Hash, optional) - wording for every string the control shows, merged over `Layered::Ui::ComboboxHelper::COMBOBOX_TEXT`: `empty:` ("No matches"), `create:` ("Add “%{term}”"), `min_chars:` ("Type %{count} characters to search."), `progress:` ("Showing %{shown} of %{count} matches."), `error:`, `more_error:`. Placeholders use Rails' `%{name}` syntax; `progress: nil` drops the progress line; an unknown key raises
+- `describedby` (String, optional) - extra element ids appended to the input's `aria-describedby`, for text rendered outside the control (a validation message, say)
 - `label`, `hint`, `placeholder`, `required`, `disabled`, `id`, `container` - as for a normal field
 
+Also available as a field type in `l_ui_form`: `{ attribute: :tag_ids, as: :combobox, collection: ... }`.
+
 ```erb
 <%= form_with model: @post do |f| %>
   <%= l_ui_combobox(:tag_ids, form: f,

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.25.0] - 2026-08-23
+
+### Added
+
+- `:combobox` as a form field type: a field declared `as: :combobox` renders through `l_ui_combobox`, so a form gets type-ahead filtering and token selections without dropping out to the helper by hand. The field renders its own label and hint, defaults its selection to the record's current value, and takes the field's error element into the input's `aria-describedby`. Whether the control is multiple is inferred from the attribute - an `_ids` writer, or an array column - so the same declaration posts the same shape on a new record and on an edit; pass `multiple:` to override it.
+- Field options are checked as the field is normalised, so a key the combobox cannot take names itself instead of raising "unknown keyword" mid-render. `:prompt` and `:include_blank` (carried over from `as: :select`) raise too, pointing at `placeholder:` and noting that a combobox with no selection is already blank. A remote (`url:`) field cannot look up the label of a value the record already holds, so that case raises with a pointer to `selected:`.
+
 ## [0.24.0] - 2026-08-22
 
 ### Added

data/app/helpers/layered/ui/combobox_helper.rb

@@ -13,6 +13,15 @@ module Layered
         error: "The options could not be loaded.",
         more_error: "More options could not be loaded."
       }.freeze
+
+      # The keywords +l_ui_combobox+ accepts. Its signature is keyword-only, so
+      # a :combobox field config can only carry these (unlike the other field
+      # types, whose extras become HTML attributes on the input).
+      COMBOBOX_OPTIONS = %i[
+        collection url form selected multiple create create_name reorder
+        min_chars text id label hint placeholder required disabled
+        describedby container
+      ].freeze
       # Renders a token select: a text input with type-ahead filtering whose
       # selections become removable tokens, in the style of an email recipient
       # field. Built on the ARIA combobox pattern (an +input+ with
@@ -116,11 +125,13 @@ module Layered
       #   placeholder: (String)  Input placeholder. Defaults to nothing.
       #   required:    (Boolean) Marks the label and input as required.
       #   disabled:    (Boolean) Disables the input and every token control.
+      #   describedby: (String)  Extra element ids appended to the input's +aria-describedby+, for text
+      #                          rendered outside the control (a validation message, say).
       #   container:   (Hash)    Extra HTML attributes for the wrapping <div>.
       def l_ui_combobox(name, collection: nil, form: nil, selected: nil, multiple: true,
                         create: false, create_name: nil, reorder: false, url: nil,
                         min_chars: 0, text: {}, id: nil, label: nil, hint: nil, placeholder: nil,
-                        required: false, disabled: false, container: {})
+                        required: false, disabled: false, describedby: nil, container: {})
         if collection.nil? && url.nil?
           raise ArgumentError,
                 "l_ui_combobox requires collection: (options filtered in the browser) or url: " \
@@ -157,7 +168,8 @@ module Layered
             (tag.p(hint, id: "#{id}-hint", class: "l-ui-form__hint") if hint),
             l_ui_combobox_control(id, tokens,
                                   value_name: value_name, placeholder: placeholder, hint: hint,
-                                  reorder: reorder, disabled: disabled, required: required, url: url),
+                                  reorder: reorder, disabled: disabled, required: required, url: url,
+                                  describedby: describedby),
             l_ui_combobox_listbox(id, options, tokens, multiple: multiple, url: url, text: text),
             l_ui_combobox_template(reorder: reorder, disabled: disabled),
             (l_ui_combobox_option_template if url),
@@ -203,10 +215,12 @@ module Layered
           if label.nil? && !create
             raise ArgumentError,
                   "l_ui_combobox was given selected value #{value.inspect}, which is not in the " \
-                  "collection. " +
-                  (url ? "Pass it as a [label, value] pair, since a remote collection cannot be " \
-                         "searched for its label. " : "") +
-                  "Pass create: true (with create_name:) to allow values outside it."
+                  "collection. Pass it with its label, e.g. selected: [[\"Label\", " \
+                  "#{value.inspect}]] - " +
+                  (url ? "a remote collection cannot be searched for its label. " :
+                         "a scoped or paginated collection will not contain a value the record " \
+                         "already has. ") +
+                  "Or pass create: true (with create_name:) to allow values outside the collection."
           end
 
           {
@@ -309,8 +323,9 @@ module Layered
         end
       end
 
-      def l_ui_combobox_control(id, tokens, value_name:, placeholder:, hint:, reorder:, disabled:, required:, url: nil)
-        described_by = [("#{id}-hint" if hint), "#{id}-instructions"].compact.join(" ")
+      def l_ui_combobox_control(id, tokens, value_name:, placeholder:, hint:, reorder:, disabled:, required:,
+                                url: nil, describedby: nil)
+        described_by = [("#{id}-hint" if hint), "#{id}-instructions", describedby.presence].compact.join(" ")
 
         tag.div(class: class_names("l-ui-combobox__control", "l-ui-combobox__control--disabled" => disabled),
                 data: { "l-ui--combobox-target" => "control", action: "click->l-ui--combobox#focusInput" }) do

data/app/helpers/layered/ui/form_helper.rb

@@ -5,7 +5,7 @@ module Layered
         string text email password number tel url search
         date datetime time month week
         color range file
-        select checkbox hidden
+        select checkbox hidden combobox
       ].freeze
 
       # Renders a complete form with all fields, error summary,
@@ -38,11 +38,51 @@ module Layered
                 "Provide collection: [['Label', value], ...] or collection: -> { Model.pluck(:name, :id) }"
         end
 
+        if as == :combobox && config[:collection].nil? && config[:url].nil?
+          raise ArgumentError,
+                "Field :#{attribute} is declared as :combobox but has no :collection or :url. " \
+                "Provide collection: [['Label', value], ...] to filter in the browser, " \
+                "or url: to fetch options from an endpoint as the user types"
+        end
+
+        if as == :combobox && config[:url] && !config.key?(:selected) &&
+           l_ui_field_value(record, attribute).present?
+          raise ArgumentError,
+                "Field :#{attribute} is a remote :combobox with a value already set, but no :selected. " \
+                "A remote collection cannot be searched for the label of an existing value, " \
+                "so pass it with its label, e.g. selected: [[record.user.name, record.user_id]]"
+        end
+
         label = config[:label] || attribute.to_s.humanize
 
         extras = config.except(:attribute, :as, :label, :required, :hint,
                                :collection, :placeholder, :prompt, :include_blank)
 
+        if as == :combobox
+          unusable = {
+            prompt: "Use placeholder: instead, which a combobox shows until something is selected.",
+            include_blank: "A combobox with no selection is already blank, so there is nothing to set."
+          }
+          unusable.each do |key, advice|
+            next unless config.key?(key)
+
+            raise ArgumentError,
+                  "Field :#{attribute} is a :combobox and cannot take :#{key}. #{advice}"
+          end
+
+          extras[:multiple] = l_ui_field_multiple?(record, attribute) unless config.key?(:multiple)
+
+          allowed = ComboboxHelper::COMBOBOX_OPTIONS + [:class]
+          unknown = extras.keys - allowed
+          if unknown.any?
+            raise ArgumentError,
+                  "Field :#{attribute} is a :combobox and cannot take " \
+                  "#{unknown.map { |key| ":#{key}" }.join(', ')}. Unlike the other field types, a " \
+                  "combobox takes only its own options (#{allowed.map { |key| ":#{key}" }.join(', ')}); " \
+                  "extra HTML attributes belong on container:"
+          end
+        end
+
         {
           attribute: attribute,
           as: as,
@@ -57,6 +97,12 @@ module Layered
         }
       end
 
+      # The record's current value for a field, used as the default selection
+      # for a :combobox field when +selected:+ is not given.
+      def l_ui_field_value(record, attribute)
+        record.public_send(attribute) if record.respond_to?(attribute)
+      end
+
       def l_ui_field_error_id(record, attribute)
         "#{record.model_name.param_key}_#{attribute}_error"
       end
@@ -76,6 +122,30 @@ module Layered
 
       private
 
+      # Whether a :combobox field holds several values. +l_ui_combobox+ defaults
+      # to a multiple select, but a form field is more often a single scalar
+      # attribute, which would silently cast an array of values to nil. So a
+      # field is multiple only when the attribute is plainly a collection: an
+      # +_ids+ association writer, an array column, or an attribute already
+      # holding an array. The column is asked before the value, so an array
+      # column with no default stays multiple on a new record, where its value
+      # is nil rather than an empty array.
+      def l_ui_field_multiple?(record, attribute)
+        return true if attribute.to_s.end_with?("_ids")
+        return true if l_ui_field_array_column?(record.class, attribute)
+
+        l_ui_field_value(record, attribute).is_a?(Array)
+      end
+
+      # Array columns are a PostgreSQL feature, so the flag is only carried by
+      # some adapters' columns.
+      def l_ui_field_array_column?(model_class, attribute)
+        return false unless model_class.respond_to?(:columns_hash)
+
+        column = model_class.columns_hash[attribute.to_s]
+        column.respond_to?(:array?) && column.array?
+      end
+
       def l_ui_field_type_for(model_class, attribute)
         return :string unless model_class.respond_to?(:columns_hash)
 

data/app/views/layered/ui/managed_resource/_field.html.erb

@@ -2,7 +2,7 @@
   <%= render "layered/ui/managed_resource/field_input", form: form, record: record, config: config %>
 <% else %>
   <div class="l-ui-form__group">
-    <% unless config[:as] == :checkbox %>
+    <% unless config[:as] == :checkbox || config[:as] == :combobox %>
       <%= render "layered_ui/shared/label",
                  form: form, field: config[:attribute],
                  required: config[:required], name: config[:label] %>
@@ -10,7 +10,7 @@
 
     <%= render "layered/ui/managed_resource/field_input", form: form, record: record, config: config %>
 
-    <% if config[:hint] %>
+    <% if config[:hint] && config[:as] != :combobox %>
       <p class="l-ui-form__hint" id="<%= l_ui_field_hint_id(record, config[:attribute]) %>">
         <%= config[:hint] %>
       </p>

data/app/views/layered/ui/managed_resource/_field_input.html.erb

@@ -35,6 +35,22 @@
     <%= form.select(attribute, choices, select_options,
                     class: field_class.call("l-ui-select"), **base_opts, **extras) %>
   </div>
+<% elsif config[:as] == :combobox %>
+  <%
+    collection = config[:collection]
+    choices = collection.respond_to?(:call) ? collection.call : collection
+    combobox_opts = extras
+    selected = combobox_opts.key?(:selected) ? combobox_opts.delete(:selected) : l_ui_field_value(record, attribute)
+    container = (combobox_opts.delete(:container) || {}).dup
+    container[:class] = token_list(container[:class], extra_class) if extra_class
+    describedby = [l_ui_field_error_id(record, attribute),
+                   combobox_opts.delete(:describedby).presence].compact.join(" ")
+  %>
+  <%= l_ui_combobox(attribute, form: form, collection: choices, selected: selected,
+                    label: config[:label], hint: config[:hint],
+                    placeholder: config[:placeholder], required: config[:required],
+                    describedby: describedby,
+                    container: container, **combobox_opts) %>
 <% elsif config[:as] == :checkbox %>
   <div class="l-ui-checkbox-container">
     <%= form.check_box(attribute, class: field_class.call("l-ui-checkbox"), **base_opts, **extras) %>

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.24.0"
+    VERSION = "0.25.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - layered.ai