hibiki_rails 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd126c85e743e5ec9c89e54a1ffaba4cb04e6b6b0ef89868d60023168a0936a7
-  data.tar.gz: 00b4dfa1606348df1039cf5b69d1129c170fd418966b3db120964b71eba1e1c6
+  metadata.gz: eb224598ce236ad6d2f55b9648fbcb4644a478e1c86db2839dc3648207cd0605
+  data.tar.gz: 2c4c73dbc34338aca84fde08bf520e47dcc5920a7e4a6403ce9b4ee6d7ec62b6
 SHA512:
-  metadata.gz: 3c1e7d75c946f79cc898c20c2c3a8457ba78c152963f8b8155dd70a26308c138b31acc4b7a732e037d6bc28e933fb542a509d2dabee2e03602727d7e5e81b6d6
-  data.tar.gz: 6edf4361a4edbda81b933167cb6a7e08030cb50aac694c601a22c2210036eab5c56b101a449d3ea174a5485347e7c9c6e1cc86f9da123cbfe02e0e1ed34f41dd
+  metadata.gz: 5cace159e074313892f3736f5bed6220e1852fc71d85ee5b063af80c31471662f492d945ad57b5589543b54f43d2f4bac3dce3fdf8718fc0b8b1df18d0f5e756
+  data.tar.gz: 99a518942cc899684e94951d88fea9a08524c83327ae61cc5a924356b16485b33a14cc51fc9fcac3d8dc67d71f96c41ef5f8915d0b97349bc4ed0f74db3de556

data/CHANGELOG.md

@@ -4,6 +4,173 @@ 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
+
+**`Hibiki::Rails.record_equals` — a per-signal comparator for ActiveRecord
+records.** `ActiveRecord#==` compares class and id only, so a stale record is
+`==` to its edited reload and a signal write carrying the fresh one is silently
+dropped. Pass the comparator per signal and the write goes through:
+
+```ruby
+state(:items, equals: Hibiki::Rails.record_equals) { fetch }
+```
+
+It compares class + `attributes`, recurses through arrays, and falls back to
+`==` for everything else. It needs hibiki 0.3.0's `equals:` (see the dependency
+change below), which is honored at both of the graph's equality gates — the
+write gate and the flush-time check — so a change that passes the comparator
+actually reaches the page. This is opt-in sugar that makes the snapshot pattern
+forgiving; "records stop at the boundary" stays the documented default, and a
+comparator still cannot see an in-place mutation that never enters the write
+path.
+
+**A development-mode warning for the write that pattern swallows.** When a
+`State` write is dropped by the default `==` but the old and new values'
+`attributes` differ — the classic silent-stale-UI debugging session — the log
+now says so and points at the docs. Development only (never test or
+production), zero semantic change: the write is still dropped.
+
+### Changed
+
+**The scaffold's row projection is gone — records now cross the boundary as
+frozen snapshots.** `app/models/book_row.rb` is no longer generated. The query
+object's `rows` returns real records, hardened at the boundary —
+
+```ruby
+def rows
+  @rows ||= window_scope.strict_loading.map { it.readonly!; it.freeze }
+end
+```
+
+— and the channels' `rows`/`row` deriveds compare them with
+`equals: Hibiki::Rails.record_equals`. What the `Data` projection's structural
+`==` used to provide, the comparator provides; what it could never provide, the
+freeze triple does: an attribute write raises `FrozenError`, `save` raises
+`ActiveRecord::ReadOnlyRecord`, and an unpreloaded association walk raises
+`ActiveRecord::StrictLoadingViolationError` instead of firing a lazy query off
+the graph thread. Views print a `belongs_to` label as `book.author&.name`
+directly, so **the scaffold no longer injects a `delegate` per `belongs_to`
+into the model** — the model injection is the `after_commit` ping alone. The
+member channel's fetch preloads its associations (`includes(...) +
+strict_loading`) for the same reason.
+
+Existing scaffolded apps keep working untouched: their `book_row.rb` and
+delegates are app code, and the runtime reads none of it. Re-running a scaffold
+with `--force` moves the resource over; the generator never deletes, so the
+orphaned `*_row.rb` stays on disk for you to remove.
+
+**The hibiki dependency floor is `~> 0.3`** (per-signal `equals:`, shipped in
+hibiki 0.3.0). Everything 0.2 provided still holds; generated channels now rely
+on the comparator being consulted at both equality gates.
+
+**The page control and the field-error line are shared partials now.** Each
+scaffold used to write its own copy per resource; both are presentation-only,
+so they are emitted once per app instead — `app/views/shared/_pagination.html.erb`
+and `_field_error.html.erb` (under `--phlex`: `Views::Shared::Pagination` and
+`Views::Shared::FieldError` in `app/views/shared/`). Everything resource-shaped
+reaches the page control as locals from the list partial. A second scaffold
+finds the files present and leaves them; if they were generated under a
+different `--css` style, a notice says so instead of silently restyling every
+other resource's control.
+
+**Pagination renders above the list as well as below**, so a long page starts
+with a control in reach. Both copies live inside the re-rendered fragment and
+carry distinct ids (`books_pagination_top` / `books_pagination`), so idiomorph
+updates them in place.
+
+Re-running a scaffold with `--force` moves the list over to the shared
+partials and prints a notice naming the now-dead per-resource copies — the
+generator never deletes them itself.
+
+**The form's error summary is a shared partial too** —
+`app/views/shared/_form_errors.html.erb` (under `--phlex`:
+`Views::Shared::FormErrors`), rendered by every scaffolded full-page form. The
+resource name comes off the record at render time, so one file serves every
+scaffold. Under `--css=tailwind` and `--css=daisyui` the block is styled as a
+red alert panel instead of the scaffold-stock `style="color: red"`, which
+`--css=none` keeps.
+
+### Fixed
+
+**The `hibiki_busy.css` import lands directly below `@import "tailwindcss";`**
+instead of at the end of the entry stylesheet — appending placed it after
+`@plugin` lines, and CSS requires every `@import` before any other statement.
+Also fixed: re-running a scaffold in a tailwindcss-rails app
+(`app/assets/tailwind/application.css`) duplicated the import on every run,
+because the idempotence probe checked the wrong path spelling.
+
 ## 0.5.1 — 2026-08-08
 
 ### Changed

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

@@ -87,10 +87,33 @@ module Hibiki
           spinner: "loading loading-spinner loading-xs",
           warning_text: "text-warning",
           error_text: "text-error text-sm mt-1",
+          # The full-form error summary. Plain Tailwind on purpose, so both
+          # styled variants share it via the merge — an addition (2026-08-09),
+          # not a transcription: the reference apps carried the scaffold-stock
+          # `style="color: red"` block, which --css=none still emits.
+          error_summary: "rounded-md border border-red-200 bg-red-50 p-4 mb-6",
+          error_summary_title: "text-sm font-semibold text-red-800",
+          error_summary_list: "mt-2 list-disc list-inside text-sm text-red-700",
           muted: "opacity-60 italic",
           muted_inline: "opacity-60",
           counts: "ml-auto text-sm opacity-70",
-          pagination_nav: "join mt-2 mx-auto flex justify-center w-fit"
+          # 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",
+
+          # 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:
@@ -135,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: "mt-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