hibiki_rails 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d708875aa67bf5d9b9137ac8d9bb05cf23604db936011706d068ec0b7116429c
-  data.tar.gz: 941b16f996127706d699e8812cf712b755c0f833f7a04c9e71912844421645ba
+  metadata.gz: eb224598ce236ad6d2f55b9648fbcb4644a478e1c86db2839dc3648207cd0605
+  data.tar.gz: 2c4c73dbc34338aca84fde08bf520e47dcc5920a7e4a6403ce9b4ee6d7ec62b6
 SHA512:
-  metadata.gz: 74175d980c70f1b4ea1bb9ba593ef9940326eccfce6c783ceefdebfb2a0659706faa1040393759549366c5880ea23459740e0f3f280e64fb47a4bc32a371f69c
-  data.tar.gz: c88a903f15b13516310beb32a7ed741942c49ae65823a6422fb36823400a9fea420ae08bd2fe047bc1d2e6ff3e38cef8f86c0665eeee6014e0f495c880ad90a4
+  metadata.gz: 5cace159e074313892f3736f5bed6220e1852fc71d85ee5b063af80c31471662f492d945ad57b5589543b54f43d2f4bac3dce3fdf8718fc0b8b1df18d0f5e756
+  data.tar.gz: 99a518942cc899684e94951d88fea9a08524c83327ae61cc5a924356b16485b33a14cc51fc9fcac3d8dc67d71f96c41ef5f8915d0b97349bc4ed0f74db3de556

data/CHANGELOG.md

@@ -4,6 +4,76 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.7.0 — 2026-08-12
+
+### Added
+
+**`hibiki:rails:multiselect` — a dropdown multi-select over a
+`has_many :through`, layered onto a scaffolded resource.**
+
+```
+bin/rails g hibiki:rails:multiselect Album Song Track
+```
+
+Owner and target must exist and be migrated; the join model is generated when
+missing (a `belongs_to` pair with `touch:` on the owner side — a join write IS
+an owner change — and a unique index over the pair) and named off the owner's
+reflection when the `has_many :through` is already declared, where the third
+argument may be omitted. An existing join gets `touch: true` added to its
+`belongs_to`.
+
+The channel half is a generated concern (`AlbumsChannel::SongsMultiselect`
+under `app/channels/concerns/`) that wraps `build_graph`, `list_locals` and
+`edit` with `super` via a prepended module — one `include` line is the
+channel's only edit, and the concern's public `toggle_song` / `search_songs`
+methods are client-invocable actions like any other. The form object gains
+`reactive_association :songs`.
+
+The selection is owned by the graph, not the form markup: each checkbox sends
+its own toggle carrying its checked state (a set, so two tabs converge), and
+the submit payload never carries the ids. That is what keeps the built-in
+searchable filter honest — narrowing the option list can never drop
+selections it hides. Options are capped (`--limit`, default 50) with a
+LIMIT+1 fetch whose extra row becomes the "type to narrow" hint — no COUNT
+per keystroke. `--skip-search` drops the filter AND the cap, which would
+strand the options it hides. `--label` overrides the inferred display column;
+`--phlex` and `--css` are detected from what the scaffold left behind.
+
+**A multiple `<select>`'s full selection now reaches the channel, and
+`ReactiveForm` can carry a collection's ids.** Two halves shipped together:
+the client collects every FormData entry of a `[]`-suffixed field name as an
+array under the bare key (previously last-wins, so a multi-select submitted
+only one option; non-`[]` duplicate keys stay last-wins on purpose — the
+hidden-field checkbox convention depends on it), and
+`reactive_association :tags` on a `ReactiveForm` defines a `tag_ids` signal
+that hydrates from the record's ids reader and commits through the
+association writer, casting each id via the target model's primary-key type.
+
+**`hibiki:rails:form` — re-derive a resource's form from its validators.**
+`bin/rails g hibiki:rails:form Book` reads the migrated schema and rewrites the
+validator-shaped files only: the `ReactiveForm` (its `live_errors` clauses) and
+the two form views (number-field bounds, requiredness). Everything else the
+scaffold wrote is untouched, and Thor still asks per file before replacing
+edits. `--skip-views` limits it to the form object; the view layer and css
+variant are detected from the files a previous run left, with `--phlex` and
+`--css` as overrides. An optional field list chooses order and subset, never
+facts.
+
+### Changed
+
+**Scaffolded partials pass a generic `extras: {}` hash down the
+list → row → row form chain, in both view layers.** The extension point
+add-on generators ride: merge locals into the broadcast under one key and
+they arrive at the row form with no partial edits. Existing scaffolds keep
+working untouched — a generator that needs the hash on pre-0.7.0 output
+threads it in with a `compat` notice.
+
+**The scaffold's empty-`live_errors` notice now recommends
+`bin/rails g hibiki:rails:form Book`** — on its own line, with no retyped field
+list — instead of re-running `scaffold_controller` with the full arguments. The
+migration the scaffold wrote preserves the argument order, so once it has run
+the schema answers both order and facts.
+
 ## 0.6.0 — 2026-08-10
 
 ### Added

data/README.md

@@ -73,6 +73,9 @@ bin/rails g hibiki:rails:scaffold_controller Book
 
 # Same, but you pick the field order; everything else still comes from the model
 bin/rails g hibiki:rails:scaffold_controller Book title:string author:references
+
+# After adding validators: re-derive the form and its views, touching nothing else
+bin/rails g hibiki:rails:form Book
 ```
 
 Your plain `rails g scaffold` is untouched. The generated markup is styled to
@@ -91,6 +94,12 @@ Listing the fields yourself only chooses their order and which ones appear — t
 model still answers everything else, so the live validation, a number field's
 `min:`/`max:` and a `belongs_to`'s display label all survive the choice.
 
+Because the live validation is derived from the model's validators, a scaffold
+generated before its migration ran starts with none. `hibiki:rails:form` is the
+catch-up: it rewrites only the `ReactiveForm` and the two form views from the
+schema as it stands now, asks before replacing anything you edited, and takes
+`--skip-views` to rewrite the form object alone.
+
 Your models are edited, not just read: the one being scaffolded gains the
 `after_commit` broadcast that makes writes from anywhere reach an open list, and
 each model a `belongs_to` points at gains the `has_many` half plus a ping of its

data/app/assets/javascripts/hibiki.js

@@ -104,6 +104,24 @@ const controlValue = (control) => {
   return control.value
 }
 
+// A trailing [] is a serialization artifact, not part of the attribute name:
+// the channel payload is JSON, where arrays are native.
+const payloadKey = (name) => (name.endsWith("[]") ? name.slice(0, -2) : name)
+
+// A submitted form's contribution to the payload. A []-named field collects
+// EVERY entry as an array under the bare key; other duplicate keys stay
+// last-wins, which is what lets Rails' hidden-field checkbox convention
+// submit "1" when checked and "0" when not.
+const formPayload = (form) => {
+  const data = new FormData(form)
+  const payload = {}
+  for (const key of new Set(data.keys())) {
+    const all = data.getAll(key)
+    payload[payloadKey(key)] = key.endsWith("[]") ? all : all.at(-1)
+  }
+  return payload
+}
+
 // The subclassable base: one channel subscription per controller element,
 // identified by a per-page-load cid (data-<identifier>-cid-value).
 export class ChannelController extends Controller {
@@ -577,9 +595,9 @@ export default class HibikiController extends ChannelController {
       ? JSON.parse(control.dataset.hibikiWith)
       : {}
     if (event.type === "submit") {
-      Object.assign(payload, Object.fromEntries(new FormData(control)))
+      Object.assign(payload, formPayload(control))
     } else if (control.name && (event.type === "change" || event.type === "input")) {
-      payload[control.name] = controlValue(control)
+      payload[payloadKey(control.name)] = controlValue(control)
     }
     // perform stamps `hbk` after this merge, so a field literally named hbk
     // loses to the seq rather than corrupting it.

data/lib/generators/hibiki/rails/css_variant.rb

@@ -99,7 +99,21 @@ module Hibiki
           counts: "ml-auto text-sm opacity-70",
           # my-, not mt-: the control renders above the list as well as below,
           # and the top copy needs the gap on its other side.
-          pagination_nav: "join my-2 mx-auto flex justify-center w-fit"
+          pagination_nav: "join my-2 mx-auto flex justify-center w-fit",
+
+          # The multiselect dropdown (hibiki:rails:multiselect). One structure
+          # for every variant: DaisyUI's dropdown opens on :focus-within, the
+          # tailwind override hand-rolls the same rule with group-focus-within,
+          # and under --css=none nothing hides the panel so the list renders
+          # inline — unstyled, still functional.
+          dropdown: "dropdown w-full",
+          dropdown_trigger: "select w-full items-center",
+          dropdown_panel: "dropdown-content bg-base-100 rounded-box z-10 mt-1 w-full p-2 shadow-md",
+          option_list: "menu w-full max-h-60 flex-nowrap overflow-y-auto p-0",
+          option_label: "label cursor-pointer justify-start gap-2",
+          option_note: "p-2 opacity-60 italic",
+          checkbox_sm: "checkbox checkbox-sm",
+          filter_input: "input input-sm w-full mb-2"
         }.freeze
 
         # DaisyUI is a plugin over Tailwind, and the merge says so literally:
@@ -144,7 +158,16 @@ module Hibiki
           muted: "text-gray-500 italic",
           muted_inline: "text-gray-400",
           counts: "ml-auto text-sm text-gray-500",
-          pagination_nav: "my-2 mx-auto flex justify-center w-fit -space-x-px rounded-md shadow-sm"
+          pagination_nav: "my-2 mx-auto flex justify-center w-fit -space-x-px rounded-md shadow-sm",
+          dropdown: "group relative w-full",
+          dropdown_trigger: "#{FIELD_FULL} flex cursor-pointer items-center",
+          dropdown_panel: "absolute inset-x-0 z-10 mt-1 hidden rounded-md border border-gray-200 " \
+                          "bg-white p-2 shadow-lg group-focus-within:block",
+          option_list: "max-h-60 space-y-1 overflow-y-auto",
+          option_label: "flex cursor-pointer items-center gap-2 py-1 text-sm",
+          option_note: "p-2 text-gray-500 italic",
+          checkbox_sm: CHECKBOX,
+          filter_input: "#{FIELD_FULL} mb-2 text-sm"
         ).freeze
 
         # Every lookup misses, so every class argument is omitted entirely.

data/lib/generators/hibiki/rails/form/USAGE

@@ -0,0 +1,24 @@
+Description:
+    Regenerates a resource's ReactiveForm and its form views from the model's
+    schema and validators. Run it after adding or changing validators so
+    live_errors, number-field bounds and requiredness match the model again.
+
+    The model must exist and its table must be migrated. With no field list,
+    columns and their order come from the schema; pass fields explicitly only
+    to choose a different order or subset — the facts stay the schema's.
+
+    Only the validator-shaped files are rewritten; the rest of the scaffold's
+    output is untouched. Thor asks per file before replacing anything you have
+    edited. The view layer and css variant are detected from the files a
+    previous scaffold left; --phlex and --css override.
+
+Example:
+    bin/rails generate hibiki:rails:form Book
+
+    This will rewrite:
+        app/forms/book_form.rb
+        app/views/books/_form.html.erb
+        app/views/books/_book_form.html.erb
+
+    Under --phlex, the views are app/views/books/{form,row_form}.rb instead.
+    Pass --skip-views to rewrite only app/forms/book_form.rb.

data/lib/generators/hibiki/rails/form/form_generator.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/resource_helpers"
+require_relative "../generator_helpers"
+require_relative "../scaffold_helpers"
+require_relative "../scaffold_view_helpers"
+require_relative "../scaffold_phlex_helpers"
+require_relative "../scaffold_post_install"
+require_relative "../scaffold_shared_views"
+require_relative "../scaffold_schema"
+require_relative "../css_variant"
+
+module Hibiki
+  module Rails
+    module Generators
+      # Re-derives the validator-shaped slice of a scaffolded resource: the
+      # ReactiveForm (live_errors) and the two form views (bounds,
+      # requiredness). Run it after adding or changing validators on the model;
+      # everything else the scaffold wrote is deliberately out of scope, so a
+      # customized index or controller is never put at risk over a validator.
+      #
+      # Always the introspection path: the model and its table must exist,
+      # because validators are the one thing this generator is for and only a
+      # live model can answer them. A field list is optional and chooses order
+      # and subset only — the facts stay the schema's, like the scaffold's own
+      # merge.
+      class FormGenerator < ::Rails::Generators::NamedBase
+        include ::Rails::Generators::ResourceHelpers
+        include GeneratorHelpers
+        include ScaffoldHelpers
+        include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
+        include ScaffoldPostInstall
+        include ScaffoldSharedViews
+
+        # The scaffold's templates, reused wholesale — this generator re-emits
+        # a subset of that output and must never drift from it. Its own
+        # source_root stays beside its own USAGE (Base#usage_path resolves
+        # ../USAGE from source_root, and pointing it at the scaffold's tree
+        # would serve the scaffold's help text).
+        SCAFFOLD_TEMPLATES = File.expand_path("../scaffold_controller/templates", __dir__)
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Regenerates a resource's ReactiveForm and form views from the " \
+             "model's schema and validators."
+
+        argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+        class_option :css, type: :string, enum: CssVariant::NAMES,
+                           desc: "Markup variant for the form views (default: detect)"
+        class_option :skip_views, type: :boolean, default: false,
+                                  desc: "Rewrite only the form object — leave the form views alone"
+        class_option :phlex, type: :boolean,
+                             desc: "Emit Phlex form components (default: detect from existing views)"
+
+        def check_phlex_wiring
+          warn_without_phlex_rails unless skip_views?
+        end
+
+        # Resolving the schema first means a missing model or an unmigrated
+        # table aborts before anything is written.
+        def resolve_schema
+          schema
+          @new_app_dirs = %w[app/forms].reject { exists?(it) }
+        end
+
+        def create_form
+          template "form.rb.tt", form_path
+        end
+
+        def create_views
+          return if skip_views?
+
+          if phlex?
+            template "views/form.rb.tt", view_path("form.rb")
+            template "views/row_form.rb.tt", view_path("row_form.rb")
+          else
+            template "views/_form.html.erb.tt", view_path("_form.html.erb")
+            template "views/_row_form.html.erb.tt", view_path("_#{row_form_partial}.html.erb")
+          end
+
+          create_form_shared_views
+        end
+
+        def post_install
+          restart_notice
+          shared_views_notice
+          skipped_notice
+          live_errors_notice
+          uniqueness_notice
+        end
+
+        private
+
+        # The same layering as the scaffold's, minus nothing: the css-variant
+        # fork holds only the page control today, but an app's own
+        # lib/templates override must keep winning first either way.
+        def source_paths
+          @source_paths ||= [*self.class.source_paths_for_search,
+                             *phlex_source_paths,
+                             File.join(SCAFFOLD_TEMPLATES, css_variant.to_s),
+                             File.join(SCAFFOLD_TEMPLATES, "shared")]
+        end
+
+        def phlex_source_paths
+          return [] unless phlex?
+
+          [File.join(SCAFFOLD_TEMPLATES, "phlex", css_variant.to_s),
+           File.join(SCAFFOLD_TEMPLATES, "phlex", "shared")]
+        end
+
+        # Unlike the scaffold pair, the model is REQUIRED on both branches: an
+        # argument list here chooses order and subset, never facts, because
+        # facts with no validators behind them are exactly the output this
+        # generator exists to replace.
+        def schema
+          @schema ||= if attributes.any?
+                        ScaffoldSchema.from_attributes(attributes, model: model_class)
+                      else
+                        ScaffoldSchema.from_model(model_class)
+                      end
+        end
+
+        # Aborts rather than emitting a form with nothing derived — like the
+        # scaffold's own model_class, but with no field-list escape hatch.
+        def model_class
+          klass = class_name.safe_constantize
+          raise ::Rails::Generators::Error, missing_model_message unless klass
+
+          # Touch the schema here so an unmigrated table fails with our message
+          # rather than somewhere inside a template.
+          klass.tap(&:columns_hash)
+        rescue ::Rails::Generators::Error
+          raise
+        rescue StandardError
+          raise ::Rails::Generators::Error, missing_table_message
+        end
+
+        def missing_model_message
+          "No model #{class_name}. Generate the resource first:\n    " \
+            "bin/rails g hibiki:rails:scaffold #{name} title:string"
+        end
+
+        def missing_table_message
+          "#{class_name} has no table yet. Run bin/rails db:migrate first"
+        end
+
+        def skip_views? = options[:skip_views]
+
+        # Which view layer a previous scaffold left behind. app/views/<res>/
+        # form.rb only ever comes from a --phlex run (the ERB layer's file is
+        # _form.html.erb), so its presence is the layer answer; --phlex and
+        # --no-phlex override for the odd case.
+        def phlex?
+          return @phlex if defined?(@phlex)
+
+          @phlex = options[:phlex].nil? ? exists?(view_path("form.rb")) : options[:phlex]
+        end
+
+        def css_variant
+          @css_variant ||= (options[:css] || CssVariant.detect(destination_root)).to_sym
+        end
+
+        def css(token) = CssVariant.token(css_variant, token)
+        def css? = css_variant != :none
+      end
+    end
+  end
+end

data/lib/generators/hibiki/rails/multiselect/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Adds a dropdown multi-select for a has_many :through association onto a
+    resource that hibiki:rails:scaffold_controller already generated.
+
+    Owner and Target must exist and be migrated. Join is required only when
+    the owner doesn't declare the association yet — the join model and its
+    migration are generated (belongs_to pair, touch: on the owner side, a
+    unique index over the pair), and the has_many :through is injected into
+    the owner.
+
+    The channel gains one `include`; everything else lives in a generated
+    concern under app/channels/concerns that wraps build_graph/list_locals
+    with super. The selection is owned by the graph (the form's <target>_ids
+    signal), so filtering the option list can never drop hidden selections.
+
+    The option list is capped (OPTIONS_LIMIT in the concern, --limit to
+    choose it); the cap is dropped under --skip-search, where it would strand
+    the options it hides. Scaffolds generated before 0.7.0 lack the extras:
+    hash the view rides on — it is threaded through their partials
+    automatically.
+
+Examples:
+    bin/rails g hibiki:rails:multiselect Album Song Track
+
+    bin/rails g hibiki:rails:multiselect Album Song --skip-search
+
+    bin/rails g hibiki:rails:multiselect Album Song Track --label=name --limit=25

data/lib/generators/hibiki/rails/multiselect/multiselect_generator.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/resource_helpers"
+require "rails/generators/active_record"
+require_relative "../generator_helpers"
+require_relative "../scaffold_helpers"
+require_relative "../scaffold_view_helpers"
+require_relative "../scaffold_phlex_helpers"
+require_relative "../scaffold_model_injection"
+require_relative "../scaffold_schema"
+require_relative "../css_variant"
+require_relative "../multiselect_helpers"
+require_relative "../multiselect_injections"
+
+module Hibiki
+  module Rails
+    module Generators
+      # A dropdown multi-select over a has_many :through, added onto a
+      # resource hibiki:rails:scaffold_controller already generated: a channel
+      # concern that wraps the graph (the include line is the channel's only
+      # edit), a view partial or component riding the extras: hash, an ids
+      # signal on the ReactiveForm, and the join model when it doesn't exist
+      # yet.
+      #
+      # Owner and target must exist and be migrated; the join is the one model
+      # this generator may create.
+      class MultiselectGenerator < ::Rails::Generators::NamedBase
+        include ::Rails::Generators::ResourceHelpers
+        include ::ActiveRecord::Generators::Migration
+        include GeneratorHelpers
+        include ScaffoldHelpers
+        include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
+        include ScaffoldModelInjection
+        include MultiselectHelpers
+        include MultiselectInjections
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Adds a dropdown multi-select for a has_many :through onto a " \
+             "hibiki:rails scaffold, generating the join model if needed."
+
+        argument :target, type: :string, banner: "Target"
+        argument :join, type: :string, required: false, default: nil, banner: "[Join]"
+
+        class_option :css, type: :string, enum: CssVariant::NAMES,
+                           desc: "Markup variant for the generated view (default: detect)"
+        class_option :skip_search, type: :boolean, default: false,
+                                   desc: "No filter input — also drops the option limit, " \
+                                         "which would strand options it hides"
+        class_option :limit, type: :numeric, default: 50,
+                             desc: "How many options the dropdown offers at once"
+        class_option :label, type: :string,
+                             desc: "The target column shown per option (default: infer)"
+        class_option :phlex, type: :boolean,
+                             desc: "Emit a Phlex component (default: detect from the scaffold)"
+
+        # Everything that can refuse, before anything is written.
+        def preflight
+          owner_class
+          target_class
+          check_scaffolded!
+          label_column
+          join_class_name
+          @concerns_dir_new = !exists?("app/channels/concerns")
+        end
+
+        def create_join_model
+          return unless (@join_generated = join_missing?)
+
+          template "join_model.rb.tt", join_model_path
+          migration_template "join_migration.rb.tt", "db/migrate/create_#{join_table_name}.rb"
+        end
+
+        def wire_models
+          inject_owner_associations
+          inject_join_touch
+        end
+
+        def create_concern
+          template "concern.rb.tt", concern_path
+        end
+
+        def wire_channel
+          inject_channel_include
+        end
+
+        def wire_form
+          inject_form_association
+        end
+
+        def create_view
+          if phlex?
+            template "multiselect_component.rb.tt", view_path("#{multiselect_partial}.rb")
+          else
+            template "_multiselect.html.erb.tt", view_path("_#{multiselect_partial}.html.erb")
+          end
+        end
+
+        # BEFORE the render injection: the compat probe reads "extras" from the
+        # row form, and the render line would satisfy it vacuously.
+        def thread_extras
+          thread_extras_through_partials
+        end
+
+        def wire_views
+          inject_row_form_render
+          inject_row_display
+        end
+
+        def wire_preloads
+          inject_query_preload
+          inject_member_channel_preload
+        end
+
+        def post_install
+          if @join_generated
+            say_status :migrate, "#{join_class_name} was generated — run bin/rails db:migrate " \
+                                 "before using the multiselect.", :yellow
+          end
+          if @concerns_dir_new
+            say_status :restart, "app/channels/concerns is new. " \
+                                 "Please restart if the server is running.", :yellow
+          end
+          say_status :assoc, "using #{target_class_name}##{label_column} as the option label — " \
+                             "pass --label=<column> if that's wrong", :blue
+        end
+
+        private
+
+        # The scaffold's own view layer, read from what it left on disk; an
+        # explicit --phlex wins.
+        def phlex?
+          return options[:phlex] unless options[:phlex].nil?
+
+          @phlex ||= exists?(view_path("row_form.rb"))
+        end
+
+        def css_variant
+          @css_variant ||= (options[:css] || CssVariant.detect(destination_root)).to_sym
+        end
+
+        def css(token) = CssVariant.token(css_variant, token)
+        def css? = css_variant != :none
+      end
+    end
+  end
+end

data/lib/generators/hibiki/rails/multiselect/templates/_multiselect.html.erb.tt

@@ -0,0 +1,44 @@
+<%#- ESCAPING: <%% emits runtime ERB into the generated view; a bare <% is
+     consumed here at generation time. #{...} inside an escaped tag is runtime
+     Ruby and passes through untouched. -%>
+<%%# locals: (form:, dom:, extras: {}) -%>
+<%%# The <%= target_plural %> multi-select. The graph owns the selection: each checkbox
+    sends its own toggle and the submit payload never carries the ids, so
+    options hidden by the filter are never dropped. %>
+<%% ms = extras.fetch(:<%= extras_key %>, { options: [] }) %>
+<div<%= css_attr(:label) %>><%= target_human_plural %></div>
+<div<%= css_attr(:dropdown) %>>
+  <%%# tabindex, not a <button>: focus-within keeps the panel open while boxes
+      inside are clicked, and the morphed repaint keeps focus and caret. %>
+  <div tabindex="0" role="button" id="<%%= dom %>_<%= target_plural %>"<%= css_attr(:dropdown_trigger) %>>
+    <%%= pluralize(form.<%= ids_attr %>.size, "<%= target_human_singular.downcase %>") %> selected
+  </div>
+  <div tabindex="0"<%= css_attr(:dropdown_panel) %>>
+<% if search? -%>
+    <%%# Narrows the option list only — the selection lives in the graph and
+        survives filtering. `on` debounces input events. %>
+    <%%= search_field_tag <%= wrapped_list(filter_field_args, indent: 25).lstrip %> %>
+<% end -%>
+    <ul<%= css_attr(:option_list) %>>
+      <%% ms[:options].each do |text, id| %>
+        <li>
+          <%%= label_tag "#{dom}_<%= target_singular %>_#{id}"<%= css? ? %(, class: "#{css(:option_label)}") : "" %> do %>
+            <%%# Named "checked", NOT <%= ids_attr %>[]: the graph's copy of the
+                selection is authoritative, so the submit payload must not
+                carry a subset that depends on which options are visible. %>
+            <%%= check_box_tag <%= wrapped_list(option_checkbox_args, indent: 30).lstrip %> %>
+            <span><%%= text %></span>
+          <%% end %>
+        </li>
+      <%% end %>
+      <%% if ms[:options].empty? %>
+        <li<%= css_attr(:option_note) %>>No <%= target_human_plural.downcase %> match</li>
+      <%% end %>
+<% if search? -%>
+      <%% if ms[:truncated] %>
+        <li<%= css_attr(:option_note) %>>Showing first <%%= ms[:options].size %> — type to narrow</li>
+      <%% end %>
+<% end -%>
+    </ul>
+  </div>
+</div>